void vortex_channel_set_complete_flag ( VortexChannel channel,
axl_bool  value 
)

Allows to set complete frames flag.

(Please, read security notes below)

BEEP protocol defines that an application level message must be splitted into pieces equal to or less than the channel window size. Those pieces are called frames.

This enable BEEP peers to avoid receiving large messages and other problems relationed with channel starvation. As a consequence, while receiving a message reply, represented by a RPY, ANS or NUL frame type, it could be splitted into several frames.

If you don't want to handle frames segments and then join them back into a single message you can set the complete flag. Once activated, Vortex will join all frames into a single message and deliver it to the application level using the default application delivery defined (second and first level handlers or wait reply method).

By default, every channel created have the complete flag activated.

To clarify:

1  -----------------
2 | App level | Sends a message
3  -----------------
4 | A message | Which is splitted into
5  -----------------
6 | Several frames | that frames are sent..
7  -----------------
8 | Over a channel |
9  -----------------
10  ||
11  ||
12  -----------------
13 | Over a channel |
14  -----------------
15 | Several Frames | are received from remote peer side..
16  -----------------
17 | A message | joined into a single message
18  -----------------
19 | App level | App level receive a complete message
20  -----------------

Security considerations:

When using this function, you should consider using also this function vortex_channel_set_complete_frame_limit to place a limit.

Notes about MIME and how it applies to automatic vortex MIME processing:

If you disable complete flag, a side effect is that you'll receive the raw MIME message without any processing. This implies that, if the sender peer didn't configure any MIME header then you'll receive an additional \r\n along with payload. In the case the sender peer did configure a set of MIME header, they will be received along with the payload without automatic MIME header processing and payload (MIME body) separation.

This is because any message you send with BEEP should be MIME. Vortex adds to your message a \r\n if you don't configure any MIME header, so remote BEEP peer finds your message properly formated (even if you don't care about MIME).

Now, at the remote side the BEEP peer should process the message as MIME and, in the case of vortex, this is done automatically placing a reference to the MIME body (actually your message if you didn't configure any mime header) that is returned by vortex_frame_get_payload, and a reference to the entire message returned by vortex_frame_get_content (raw MIME header + actual payload).

However, this don't applies to channels with complete flag set to false because vortex can't know where to start and finish the MIME processing because it only has fragments (not the entire message) so, MIME processing is disabled (also because other security implications..), causing vortex_frame_get_payload to return the same as vortex_frame_get_content, that is, the entire message: \r\n

  • your payload.

If you still want to process MIME for a particular frame, you can use vortex_frame_mime_process.

And, easy solution for people not using MIME to avoid receiving \r\n?

You can just skip those bytes by using the following (assuming empty MIME headers):

1 // how to get a reference to payload skipping empty mime headers
2 value = vortex_frame_get_payload (frame) + 2
3 
4 // remember to reduce frame payload size
5 size = vortex_frame_get_payload_size (frame) - 2
Parameters
channelthe channel to configure.
valueaxl_true activate complete flag, axl_false deactivates it.