VortexFrame * vortex_channel_get_reply ( VortexChannel channel,
VortexAsyncQueue queue 
)

Allows to get the next frame received on the given channel due to channel start reply piggybacking or due to a frame received while using the function vortex_channel_queue_reply as a frame received handler.

This function is used with vortex_channel_queue_reply to receive the message replies (in fact, all messages received). It also support returning the data received due to channel start piggybacking through vortex_channel_get_piggyback.

If you would like to know more about the piggyback concept, check the following section to know more about how piggyback could improve your protocol startup.

The idea is to use vortex_channel_queue_reply as a frame receive handler which queues all frames received on a queue. Then, every time vortex_channel_get_reply is called, a frame from the queue is returned.

This allows to support, using the same code, to receive a message reply either as a piggyback or as a normal reply (and any other frame received).

Let's suppose you are implementing a profile which could send an initial start message with the piggyback, so it is saved one round trip: "with one message, we send the start channel request, including the first message exchanged.".

At the remote peer, the channel creation request, with a piggyback content, could be replied, using two, standard allowed, methods:

  • A reply to the <start> message accepting the channel to be created and then reply to the implicit content received, in a separated message.
  • Or reply to the <start> message accepting the channel to be created, including inside that reply, the reply to the first piggyback message received.

This leads to a source code problem at the client side that perform a blocking wait: "It is needed a way to get, not only the piggyback, but also the same reply not using the piggyback method."

Because piggyback is closely related to the channel creation, and to avoid writing two different piece of code to manage both cases, you have two methods:

NOTE: The frame returned by this function have to be deallocated using vortex_frame_unref when no longer needed. This is an special case because all frames delivered with first and second invocation handlers are automatically managed, that is, deallocated when the frame handler scope has gone.

Because examples are more clear, here is one:

1 // create a channel making all frames received, including the
2 // piggyback to be received in a blocking way:
3 VortexChannel * channel;
4 VortexAsyncQueue * queue;
5 VortexFrame * frame;
6 
7 // create the queue to be used to perform the async wait
8 queue = vortex_async_queue_new ();
9 
10 // create the channel
11 channel = vortex_channel_new (// the connection where the channel
12  // will be created
13  connection,
14  // let vortex library to manage
15  // the next channel number available
16  0,
17  // use default channel close handling
18  NULL, NULL,
19  // set the frame receive handling
20  vortex_channel_queue_reply, queue,
21  // no channel creation notification
22  NULL, NULL);
23 
24 // now wait and process all replies and messages received
25 while (axl_true) {
26  // get the next message, blocking at this call.
27  frame = vortex_channel_get_reply (channel, queue);
28 
29  if (frame == NULL) {
30  // timeout found, do some error reporting
31  // and default action on timeout received.
32  //
33  // for our example, the default action is:
34  // keep on reading!.
35  continue;
36  }
37  printf ("Frame received, content: %s\n",
38  vortex_frame_get_payload (frame));
39 
40  // deallocate the frame received
41  vortex_frame_unref (frame);
42 }
Parameters
channelThe channel where is expected to receive a frame using the frame received handler or the initial piggyback. In the case this parameter is NULL, the function won't return the piggyback that may be received.
queueThe queue where the frame is expected to be received. The queue received, no matter the result will be deallocated.
Returns
The frame received or NULL if the timeout is expired.

References vortex_async_queue_items(), vortex_async_queue_ref(), vortex_async_queue_timedpop(), vortex_async_queue_unref(), vortex_channel_get_ctx(), vortex_channel_get_piggyback(), vortex_connection_get_timeout(), vortex_connection_is_ok(), vortex_connection_remove_on_close_full(), and vortex_connection_set_on_close_full().