SendMessage

This handler is invoked for each call to SendRtMessage, SendRtMessageRSVP or SendRtReply by an application. It must be implemented by all services which require a transmission function. If SendRtMessage or SendRtMessageRSVP or SendRtReply is called for a service without this handler, an E_NOT_CONFIGURED status is returned.

The handler is entered with the parameters validated, data references mapped to the current process (where appropriate) and a control buffer allocated and initialized with the caller's parameters. In addition, a TRANSACTION structure has been allocated and initialized. The reference to the control buffer is in the lpOutControlMsg field of the transaction structure. The caller's data buffer and buffer length are stored in the TRANSACTION structure lpData and cbDataLength fields. Other fields in the transaction structure are initialized to values which depend on which call was made, the state of the port and the parameters supplied by the caller. The caller's control message is copied into the control buffer, and is also presented as a parameter to the handler. If the service needs to modify the control message it should do so to the contents of the control buffer.

void SendMessage(
    LPSERVICEDESC pService,
    RTHANDLE hPort,
    LPGENADDR pDestAddr,
    WORD wTransId, 
    LPTRANSACTION pTransaction,
    LPBYTE pControlMsg,
    WORD wControlLength,
    WORD pExcep
);

Parameters

pService

A pointer to this service's name.

hPort

The handle for the source port (supplied by the caller).

pDestAddr

If this is an addressed service, this parameter points to a GENADDR structure that contains the destination address for the message. If the port has been connected (by ConnectRtPort) then the port's default address is given here, otherwise this is the address passed by the caller.

If this is not an addressed service, this parameter is NULL.

wTransId

The RSVP transaction ID. If this handler is called from SendRtMessage then this value will be 0 (zero), because this is a simple message. The transaction structure is still allocated in case completion will be deferred.
If this handler is called from SendRtMessageRSVP then this parameter contains the transaction ID allocated with the TRANSACTION structure. If this handler was called from SendRtReply then the parameter contains the value passed by the caller.

pTransaction

Contains a pointer to a TRANSACTION structure.

pControlMsg

Contains a pointer to the caller's control message.

wControlLength

Contains the number of bytes in the caller's control message.

pExcep

Contains a pointer where the handler must return a status value.
If E_SEND_NOT_COMPLETE is returned, and the caller specified a synchronous transaction, the calling thread is put to sleep until the service makes a call to DeliverStatus. If the caller specified asynchronous transmission, E_OK is returned to the caller. Any other value returned is returned to the caller.

Remarks

If the message can be dealt with immediately (for example, the entire action associated with the message can be completed without having to wait for a future event such as an interrupt), the control message may be released by calling ReleaseControlBuffer. If the transaction is no longer required, it too may be released. The status of the transmit operation may be returned directly through the pExcep parameter.

More commonly, the result of the transmit operation will not be known until some future time. In this case, the handler should carry out any actions required to initiate the transmission, then return an exception code of E_SEND_NOT_COMPLETE. If the transmission action is simply to enqueue the transaction for processing by the service thread, the lpOutQLink field of the TRANSACTION structure may be used for this purpose.

It is very important that no calls are made to blocking calls or that time is not spent waiting in this handler. All handlers (except the Service handler) are called by the same thread irrespective of how many threads are making system calls to the service, so it is good practice to keep execution paths short in all handlers.

See Also

RT Service handlers, SendRtMessage, SendRtMessageRSVP, SendRtReply, TRANSACTION, GENADDR, DeliverStatus, Service