INtime SDK Help
CIPort

From INtime 6.0 the INtime Service and Port objects have been deprecated.

New projects should not be started using these features, and existing projects will not work with XM mode

The CIPort class encapsulates the RT port object; it allows sending messages to and receiving messages from a port service. The CIPort class is typically used as it is.

Class members

Constructor

Destructor

Create

Send

SendRSVP

Receive

ReceiveReply

CancelTransaction

The following member variable is only available to the members of the class and its derived classes:

RTHANDLE m_hHeap;

CIPort::Constructor

The constructor has no arguments. It creates an unattached object.

CIPort::Destructor

If the object is attached, the destructor detaches it; then it destroys the object.

CIPort::Create

If the object is already attached, it is first detached. Then this call creates an RT port object and attaches it to the object.

Syntax

DWORD CIPort::Create(
    char * pszName, 
    char * pszService,
    WORD wPort, 
    WORD wTrans, 
    DWORD dwHeapSize,
    BOOLEAN bPrioQ
);

Parameters

pszName
Specifies a name that, if not empty, is used to catalog the RT object.
pszService
Provides the name of the service; this parameter is required.
wPort
A value for the port number; if this value is a null port number (the value of which is defined by the service) then the service allocates a port number from the range of numbers defined for this purpose by the service implementer.
wTrans
Specifies the maximum number of simultaneous transactions allowed at this port; internally it determines the size of the transaction table on this port.
dwHeapSize
Specifies the size of the heap for the port, in bytes.
bPrioQ
Indicates whether threads waiting for units will be queued in priority order (TRUE) or FIFO (FALSE); if omitted, FALSE is used. The result is a status indicating success or failure.

Status

E_OK
No exceptional conditions occurred.
E_MEM
creating a port requires more memory than the current process owns.
E_LIMIT
The current process reached its RT object limit, or the object directory is full.
E_SLOT
You cannot create more RT objects because the GDT is full.
E_CONTEXT
The object directory already contains the name being cataloged.
E_PARAM
The name is too long or is improperly formatted.

CIPort::Send

With this call a message is sent.

Syntax

WORD CIPort::Send(
    LPBYTE pControl, 
    WORD wCtlLen,
    PVOID pData, 
    DWORD dwDataLen,
    LPGENADDR pAddr, 
    WORD wFlags
);

Parameters

pControl
Pointer to the control message to be sent.
wCtlLen
Specifies the number of bytes in the control message.
pData
Points to the data message and is assumed NULL if omitted;
dwDataLen
Specifies the number of bytes in the data message and is assumed zero if omitted.
pAddr
Points to the destination address and is assumed NULL if omitted.
wFlags
Contains flags concerning the transmission; it may be a combination of:
CONTIGUOUS_BUFFER Specifies that pData references a contiguous buffer.
DATA_CHAIN_BUFFER Specifies that pData references a data chain block.
DATA_LIST_BUFFER Specifies that pData references the first element in a data list (buffer type fields are mutually-exclusive).
SYNC_MODE Specifies that the message should be transmitted synchronously.
ASYNC_MODE Specifies that the message should be transmitted asynchronously (the mode fields are mutually exclusive).

If wFlags is omitted, CONTIGUOUS_BUFFER and SYNC_MODE is assumed. The result is a transaction ID (if there is a data message and ASYNC_MODE was specified) or zero for a successful send, or BAD_TRANSACTION_ID for a failure. In the latter case call GetLastError to get the exception code:

Status

E_OK
No exceptional conditions occurred.
E_EXIST
The object is not attached.

CIPort::SendRSVP

With this call a message is sent, with an implied request for a reply.

Syntax

WORD CIPort::SendRSVP(
    LPBYTE pControl, 
    WORD wCtlLen,
    PVOID pData, 
    DWORD dwDataLen,
    LPGENADDR pAddr, 
    WORD wFlags,
    PVOID pReply, 
    DWORD dwReplyLen
);
WORD CIPort::SendRSVP(
    LPBYTE pControl, 
    WORD wCtlLen,
    PVOID pData, 
    DWORD dwDataLen,
    PVOID pReply, 
    DWORD dwReplyLen
);
WORD CIPort::SendRSVP(
    LPBYTE pControl, 
    WORD wCtlLen,
    PVOID pReply, 
    DWORD dwReplyLen
);

Parameters

pControl
A pointer to the control message to be sent;.
wCtlLen
Specifies the number of bytes in the control message.
pData
Points to the data message and is assumed NULL if omitted.
dwDataLen
Specifies the number of bytes in the data message and is assumed zero if omitted.
pAddr
Points to the destination address and is assumed NULL if omitted.
wFlags
Contains flags concerning the transmission; it may be a combination of:
CONTIGUOUS_BUFFER Specifies that pData references a contiguous buffer.
DATA_CHAIN_BUFFER Specifies that pData references a data chain block.
DATA_LIST_BUFFER Specifies that pData references the first element in a data list (buffer type fields are mutually-exclusive).
SYNC_MODE Specifies that the message should be transmitted synchronously.
ASYNC_MODE Specifies that the message should be transmitted asynchronously (the mode fields are mutually exclusive).
USE_RECEIVE_REPLY Use ReceiveReply to receive the response message.
USE_RECEIVE Use Receive to receive the response message (the receive fields are mutually exclusive).

If wFlags is omitted, CONTIGUOUS_BUFFER, SYNC_MODE and USE_RECEIVE_REPLY is assumed. pReply points to a buffer to receive the reply; dwReplyLen indicates the size of that buffer in bytes. Note that these last two parameters cannot be omitted. The result is a a transaction ID for a successful send, or BAD_TRANSACTION_ID for a failure. In the latter case call GetLastError to get the exception code:

Status

E_OK
No exceptional conditions occurred.
E_EXIST
The object is not attached.

CIPort::Receive

This call puts the thread in a sleep state until a message has been received, or until a timeout occurs.

Syntax

PVOID CIPort::Receive(
    LPRECEIVEINFO pReceive,
    DWORD dwTimeout
);

Parameters

pReceive
Points to a RECEIVEINFO structure, that receives information about the message.
dwTimeout
Defines how long the thread will wait and may be omitted (meaning WAIT_FOREVER). The result is a pointer to the data message or NULL if there is no data message, for a good receive; or BAD_POINTER for a bad receive (use GetLastError to obtain the actual error code).

Status

E_OK
No exceptional conditions occurred.
E_TIME
There was no message during the waiting period.
E_EXIST
The object is not attached.

CIPort::ReceiveReply

This call puts the thread in a sleep state until a reply message has been received, or until a timeout occurs.

Syntax

PVOID CIPort::ReceiveReply(
    LPREPLYINFO pReceive,
    WORD wTransID,
    DWORD dwTimeout
);

Parameters

pReceive
Points to a REPLYINFO structure, that receives information about the reply message.
wTransID
Identifies the transaction.
dwTimeout
Defines how long the thread will wait and may be omitted (meaning WAIT_FOREVER). The result is a pointer to the data message or NULL if there is no data message, for a good receive; or BAD_POINTER for a bad receive (use GetLastError to obtain the actual error code).

Status

E_OK
No exceptional conditions occurred.
E_TIME
There was no message during the waiting period.
E_EXIST
The object is not attached.

CIPort::CancelTransaction

This call cancels a pending transaction.

Syntax

DWORD CIPort::CancelTransaction(
    WORD wTransID
);

Parameters

wTransID
Identifies the transaction to cancel. The result is a status indicating success or failure.

Status

E_OK
No exceptional conditions occurred.
E_EXIST
The object is not attached.
See Also

Services & Ports