axl_bool vortex_channel_send_msg ( VortexChannel channel,
const void *  message,
size_t  message_size,
int *  msg_no 
)

Sends the message over the selected channel.

If msg_no is defined, the function will return the message number used for this delivery. This can be useful to perform a wait for the message response.

The function makes a local copy of the data received (message). Here is an example:

1 // we create some dynamically allocated message
2 char * message = axl_strdup_printf ("%d - %s ..\n", 10,
3  "some kind of very important message");
4 
5 if (!vortex_channel_send_msg (channel, message, strlen (message), NULL)) {
6  // some kind of error process and free your resources
7  axl_free (message);
8 
9 }
10 
11 // you should free dynamically allocated resources no longer
12 // used just after running vortex_channel_send_msg.
13 
14 axl_free (message);
Parameters
channelThe channel used to send the message.
messageThe message to send. The function will create a local copy so you can provide static and dinamic references.
message_sizeThe message size.
msg_noOptional reference. If defined returns the message number used for this deliver (BEEP msgno).
Returns
axl_true if no error was reported after queueing the message to be sent. Otherwise axl_false is returned. Keep in mind the function do not send the message directly. This is because the channel could be stalled at the time the message was sent or because the message is too large that requires several frames to be sent. Having said that, it is recommended to not consider a "axl_true" value returned by this function as a successful send.

MIME considerations while using this function

This function, if nothing especial is configured, assumes the message to be sent is not MIME prepared, that is, it is considered as a MIME body. In this context, the function append, at least, the MIME header separator (CR+LF) to notify no MIME header was configured, or those MIME headers configured at vortex_profiles_set_mime_type.

It could happen this not fit your requirements because you need to send another MIME header configuration, maybe one different per message. In this case, you'll have to disable automatic MIME header handling (see relevant portions about this issue at 4.2 Using MIME configuration for data exchanged under Vortex Library), and send a MIME ready message.

For example, the following could be used to send arbitrary MIME content. First, disable automatic MIME handling for the channel (it can also be done at library or profile level). This is only required once. You can do it after the channel was created.

1 // make the channel to let the application level to handle MIME configuration
2 vortex_channel_set_automatic_mime (channel, 2);

Then, at the sending phase, you'll have to build a properly formated MIME message. In our example, we'll send a MIME message with a body part defined by (message_content) and two MIME headers: Message-ID and X-Transaction-ID:

1 // prepare a MIME message
2 char * mime_message = axl_strdup_printf ("Message-ID: %s\r\nX-Transaction-ID: %s\r\n\r\n%s",
3  message_id,
4  transaction_id,
5  message_content);
6 // send it over a properly configured channel
7 if (! vortex_channel_send_msg (channel, mime_message, strlen (mime_message), NULL)) {
8  // failed to send the message, do some handling here
9  axl_free (mime_message);
10  return -1;
11 }
12 // mime message properly sent
13 axl_free (mime_message);

See a detailed discusion about MIME activation at: 4.2 Using MIME configuration for data exchanged under Vortex Library

Referenced by vortex_channel_send_msgv().