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.