ISession.Send Method (IMessage[], Int32, Int32, Int32)

Solclient

ISessionSend Method (IMessage, Int32, Int32, Int32)
version: 7.2.1.27
Sends an array of messages over the session, attempting to send them all at once.

Note that the number of messages which can be sent through a single call to this method is limited to 50.

For sessions in which Send(IMessage[],...) is used, it is recommended that TcpNoDelay be set to true (it is enabled by default). In this case, multiple messages are sent at once onto a TCP connection, and therefore there is no need to have the operating system carry out the TCP delay algorithm to cause fuller IP packets.

Namespace: SolaceSystems.Solclient.Messaging
Assembly: SolaceSystems.Solclient.Messaging (in SolaceSystems.Solclient.Messaging.dll) Version: 7.2.1.27 (7.2.1.27)
Syntax
ReturnCode Send(
	IMessage[] messages,
	int offset,
	int length,
	out int messagesSent
)
Function Send ( 
	messages As IMessage(),
	offset As Integer,
	length As Integer,
	<OutAttribute> ByRef messagesSent As Integer
) As ReturnCode
ReturnCode Send(
	array<IMessage^>^ messages, 
	int offset, 
	int length, 
	[OutAttribute] int% messagesSent
)

Parameters

messages
Type: SolaceSystems.Solclient.MessagingIMessage
Array of IMessage instances. If duplicate IMessage entries were used in the messages array, they must notbe Guaranteed messages, in this case an ArgumentOutOfRangeException is thrown
offset
Type: SystemInt32
Offset into the array of first message to send.
length
Type: SystemInt32
Number of messages to send, from offset.
messagesSent
Type: SystemInt32
Returns the number of messages that were sent.

Return Value

Type: ReturnCode
SOLCLIENT_OK if successful and all messages have been sent Or SOLCLIENT_WOULD_BLOCK if some messages cannot be accepted by the API immediately. The API signals its readiness to accept messages through a CanSend event type. The messagesSent parameter contains the number of messages sent.

Note: returning SOLCLIENT_OK means that the messages have been successfully copied to the underlying transport which does not guarantee successful delivery to the Solace appliance. In the case of persistent or non-persistent messages, the application will receive a subsequent Acknowledgement event for all messages (persistent and non-persistent) successfully delivered to the Solace appliance. For guaranteed(persistent or non-persistent) messages which cannot be accepted by the Solace appliance (quota, permission or other delivery problems), a RejectedMessageError event will be generated.

Special Buffering of Guaranteed Messages

Guaranteed messages (MessageDeliveryMode.Persistent or MessageDeliveryMode.NonPersistent) are assured by the protocol between the client and the Solace message-router. To make developers' task easier, guaranteed messages are queued for delivery in many instances:

  • While transport (TCP) flow controlled.
  • While message-router flow controlled.
  • While sessions are connecting or reconnecting.
  • While sessions are disconnected or down.

The SDK will buffer up to a publishers window size (ADPublishWindowSize ) of guaranteed messages before solClient_session_sendMsg() will either block (when SendBlocking is enabled) or return SOLCLIENT_WOULD_BLOCK (on active sessions) or return SOLCLIENT_NOT_READY (on disconnected sessions).

For the most part this is desired behavior. Transient sessions failures do not require special handling in applications. When ReconnectRetries is non-zero, the underlying transport will automatically reconnect and the publishing application does not need to concern itself with special handling for the transient reconnecting state.

Special consideration is required for applications using host lists. When a reconnect occurs on a different host, an application publishing guaranteed messages will receive the DownError event with the UnknownFlowName sub-code. When this occurs, any queued messages are flushed. Messages published after this event has been raised will be queued then sent after a subsequent connect initiated by the application by calling Connect.

Multi-threaded applications should be aware that some, but not necessarily all, messages published on one thread may be flushed due to failed reconnect, as messages published after the DownError event are not flushed. If the application chooses to republish some or all unacknowledged messages after the send queue has been flushed there is a possibility that these old, republished messages may be queued after newly published messages.

If the possibility of old messages after new messages is a concern, it is recommended that instead of calling Connect on the session that has gone down, this session should instead be destroyed and a new session created to establish a new connection.

Exceptions
ExceptionCondition
OperationErrorException Thrown when the Send operation fails, see Send(IMessage) for possible sub-codes.
ObjectDisposedException Thrown when the session is already disposed (terminal state).
FatalErrorException Thrown when an unrecoverable error occurs.
ArgumentNullException Thrown if messages is null.
ArgumentOutOfRangeException Thrown if messages has zero-length, or duplicate Guaranteed Delivery IMessage entries were passed in messages.
See Also