Sends a message from a port to a service. If the port is connected, or an address parameter is supplied, the message is sent to a remote port, if the service supports this feature.

Use this call to send a message to a service without expecting a reply. You must specify a valid pointer to some control information, even if the service or your application does not use the information. You can optionally provide a pointer and length for a data component. If you do, specify whether the data is in a single buffer or a list using the flags parameter, unless the NOTIFY_ALWAYS transmission flag is set.

You can specify that the message transmission be synchronous or asynchronous. If synchronous, this call does not return until the transmission is complete. If asynchronous, the call returns as soon as the message has been scheduled for transmission by the service. If an asynchronous transmission subsequently fails, a status message is returned to the originating port. No status message is returned if the transmission was successful.

A message will be rejected if the number of transactions being processed by the port would become greater than the number specified when the port was created.

NTXXID ntxSendRtMessage(
    NTXHANDLE hPort,
    LPGENADDR pAddress,
    LPBYTE pControl,
    DWORD dwControlLength,
    LPVOID pData,
    DWORD dwDataSize,
    DWORD dwTransmissionFlags
);

Parameters

hPort

The port where this message originates.

pAddress

The address of the destination port. This can be NULL if the port is connected, or if the service can accept messages itself.

pControl

The control message to send. There is always a control message.

dwControlLength

The size of the control message.

pData

The data part of the message, or NULL for control messages.

dwDataSize

The size of the data part of this message.

dwTransmissionFlags

This is either SYNC_MODE if the message is to be transmitted synchronously, or ASYNC_MODE if the message is to be transmitted asynchronously. SYNC_MODE is assumed if this parameter is zero. If the message is sent asynchronously, the caller must eventually collect a status message from this port which will indicate the completion status of this call.

Return Values

The transaction ID associated with this message.

Success.

BAD_TRANSACTION_ID

Failure. To determine the status, call ntxGetLastRtError.

Status

E_OK 0x0000

No exceptional conditions occurred.

E_CONTEXT 0x0005

The port is an anonymous sink port.

E_EXIST 0x0006

The port is already being deleted.

E_NOT_CONFIGURED 0x0008

The service does not have a SendMessage handler.

E_TRANSMISSION 0x000B

One of these conditions exist:

• The destination port does not exist or is invalid (short circuit).
• hardware error occurred during transmission.

E_INVALID_ADDR 0x00E2

The address parameter is not valid.

E_RESOURCE_LIMIT 0x00E6

Insufficient control buffers are available.

E_DISCONNECTED 0x00E9

The destination port is connected to another port.

E_TRANS_LIMIT 0x00EA

The transaction limit for either the port or the service has been exceeded.

E_UNBOUND 0x00EB

The port has not been bound.

E_TYPE 0x8002

The handle supplied is not for a port object.

E_PARAM 0x8004

One of these conditions exist:

• An address parameter was supplied for a non-addressed service.
• The control message length supplied is too great.

E_NUC_BAD_BUF 0x80E2

One of these conditions exist:

• The control message pointer was invalid.
• The data pointer was invalid.

E_LOCATION

The RT client on which the port was created is now invalid.

E_NTX_INTERNAL_ERROR

The DLL could not contact the RT kernel to complete the request.

Note:   Other status values may be generated by the service-specific SendMessage handler.

Requirements

See Also

Port system calls, SendMessage, ntxSendRTMessageRSVP