axl_bool vortex_channel_send_ans_rpy ( VortexChannel channel,
const void *  message,
size_t  message_size,
int  msg_no_rpy 
)

Allows to perform an ANS/NUL reply to a given MSG frame received.

While replying to a message received, a MSG frame type, the server side may chose to reply to it using a RPY frame type. But, it may chose to use a series of ANS frame type ended by a NUL frame type. This message exchange type is termed as one-to-many.

This allows to issue a MSG request and to receive several replies to the same message because the server side have to perform several tasks to complete the MSG request received. Instead of keep on waiting to all tasks to be completed, the server side could send an ANS reply for each partial task completed. Once all tasks are completed, the server side will send the last reply frame type using a NUL frame type.

Previous description allows client application to get actual responses from the server side as long as each piece of the global task gets completed.

We have described that a series of ANS frame types must be used ended by a NUL frame type. This description is handled using both function vortex_channel_send_ans_rpy and vortex_channel_send_ans_rpyv, to generate ANS message replies and using vortex_channel_finalize_ans_rpy to generate the last one, payload-empty message, using NUL frame type.

Let's see a piece of code:

1 while (some yet not ready condition) {
2  // perform some task which is returned by a function
3  response = function_which_returns_the_task (&response_size);
4 
5  // send the reply
6  if (!vortex_channel_send_ans_rpy (channel, response,
7  response_size,
8  // the MSG num we are replying to
9  msg_no_rpy) {
10  // well, we have found an error while sending a message
11  manage_my_specific_error ();
12  }
13 
14  // update the condition to break the loop
15  update_my_internal_loop_conditions ();
16 }
17 
18 // we have finished, signal peer client side that no more ANS
19 // will be received.
20 if (!vortex_channel_finalize_ans_rpy (channel, msg_no_rpy) {
21  // well, we have found an error while sending a message
22  manage_my_especific_error ();
23 }

This message style exchange is especially suited for those situations where the client peer wants to get access to some huge or unlimited content, such as streaming, making a request such as: "get that huge file" to be replied by the server side with a series of ANS replies ended by a NUL message.

Vortex Library is prepared to send messages no matter how huge they are, but you have to consider the size of that set of messages in memory. Oversizing you memory resources will cause your app to start trashing or, in some OS, to just fail with unpredictable behaviors.

As a conclusion:

  • You can always use one-to-one message exchange using MSG/RPY but, if the message content replied is considerable, i.e. 4 megabytes, you should consider starting to use MSG/ANS message exchange style.
  • Using a MSG/RPY message exchange having considerable sized message replies, will cause the client peer side to get no response until all frames from the remote side have been received and joined into one single message. This could not be a problem, but, in the context of graphical user interfaces, the overall effect is that your applications is hanged, without knowing if the server side is death or is still processing current reply issued.
  • Using the ANS/NUL reply semantic is an elegant way to reply several messages to the same message because allows you to support that process on top of the Vortex Library API rather than splitting your message into several pieces to be sent to the remote side.
  • Once started an one-to-many reply using ANS, it must be ended using the NUL frame type (vortex_channel_finalize_ans_rpy).
Parameters
channelThe channel where the reply will be performed.
messageThe message replied.
message_sizeThe message size replied.
msg_no_rpyMessage number to reply.
Returns
axl_true if the given reply was sent, otherwise axl_false is returned.

NOTE: See MIME considerations described at vortex_channel_send_msg which also applies to this function.

References VORTEX_FRAME_TYPE_ANS.

Referenced by vortex_channel_send_ans_rpyv().