INtime SDK Help
SendRtMessage
INtime SDK v6 > About INtime > INtime Kernel > Ports > SendRtMessage

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. You will receive a compiler warning by default if you use these calls.

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.

WORD SendRtMessage(
    RTHANDLE hPort,
    LPGENADDR lpAddress,
    LPBYTE lpControl,
    WORD wControlLength,
    LPVOID lpData,
    DWORD dwDataSize,
    WORD wTransmissionFlags
);

Parameters

hPort
A handle for the port where the message is sent.
lpAddress
A pointer to the GENADDR structure indicating the destination of the message. If this parameter is NULL and the port is not connected and the service supports transmission to remote ports, an error is returned.
lpControl
A pointer to the control message to be sent.
wControlLength
The number of bytes in the control message.
lpData
A pointer to a contiguous or non-contiguous data buffer containing the data message or NULL.
dwDataSize
The number of bytes in the data message.
wTransmissionFlags
  • The parameter default is a contiguous buffer and synchronous transmission.
  • Some of the following values may be combined to form the flags parameter.
  • The value is interpreted as follows:
CONTIGUOUS_BUFFER Specifies that lpData reference a contiguous buffer.
DATA_CHAIN_BUFFER Specifies that lpData reference a data chain block.
DATA_LIST_BUFFER Specifies that lpData reference 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.
NOTIFY_ALWAYS Specifies that a status message should always be returned if ASYNC_MODE flag is set.
Note:   The mode fields are mutually exclusive.

Return Values

A transaction ID which identifies this particular message transaction. If no data is being sent (lpData is NULL), the value returned is 0 (zero).
Success.
BAD_TRANSACTION_ID
Failure. To determine the status, call GetLastRtError.

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).
  • A 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.
Note:   Other status values may be generated by the service-specific SendMessage handler.

Requirements

Versions Defined in Include Link to
INtime 3.0 intime/rt/include/rtbase.h rt.h rt.lib

See Also

Port system calls, SendMessage, SendRtMessageRSVP, GENADDR