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:

1. Set an on created handler at the vortex_channel_new or vortex_channel_new_full and you'll receive, as the first frame, the piggyback. For this case, the first frame received over the channel will either the piggyback or, if not defined, the first frame received.

2. If you need to make synchronous, the code you are doing, set the vortex_channel_queue_reply as the frame received handler and then, once the channel is created call to vortex_channel_get_reply. This method works the same as 1.

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:

 // create a channel making all frames received, including the
 // piggyback to be received in a blocking way:
 VortexChannel      * channel; 
 VortexAsyncQueue   * queue;
 VortexFrame        * frame;

 // create the queue to be used to perform the async wait
 queue   = vortex_async_queue_new ();

 // create the channel
 channel = vortex_channel_new (// the connection where the channel
                               // will be created
                               connection, 
                               // let vortex library to manage
                               // the next channel number available
                               0, 
                               // use default channel close handling
                               NULL, NULL,
                               // set the frame receive handling
                               vortex_channel_queue_reply, queue,
                               // no channel creation notification
                               NULL, NULL);
 
 // now wait and process all replies and messages received
 while (axl_true) {
     // get the next message, blocking at this call.
     frame = vortex_channel_get_reply (channel, queue);

     if (frame == NULL) {
          // timeout found, do some error reporting
          // and default action on timeout received.
          //
          // for our example, the default action is:
          //     keep on reading!.
          continue;
     }
     printf ("Frame received, content: %s\n",
             vortex_frame_get_payload (frame));
    
     // deallocate the frame received
     vortex_frame_unref (frame);
 }

Parameters:

	channel	The 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.
	queue	The 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.