vortex.Channel — PyVortexChannel class: BEEP channel creation and management

Intro

API documentation for vortex.Channel object representing a BEEP channel.

Module API

class vortex.Channel
send_msg(content[, size])

Allows to send a message (content) with the size provided.

Parameters:
  • content (String (may contain binary data like 0)) – The content to send.
  • size (Integer) – Optional content size indication or -1 to let the function to deduce string size. In the case you work with unicode strings, you use use -1 to let the method to deduce the right size because API requires byte-length while python provides the char length.
Return type:

Returns the msg_no used for the send operation or None if the send operation fails.

Note the proper manner to detect if the send operation was done is to use:

msg_no = channel.send_msg (content, size)
if msg_no is None:
   print ("ERROR: failed to send message")
   # return or appropriate error recover
send_msg_more(content[, size])

Allows to send a message (content) with the size provided flagging all frames with more flag on.

Parameters:
  • content (String (may contain binary data like 0)) – The content to send.
  • size (Integer) – Optional content size indication or -1 to let the function to deduce string size. In the case you work with unicode strings, you use use -1 to let the method to deduce the right size because API requires byte-length while python provides the char length.
Return type:

Returns the msg_no used for the send operation or None if the send operation fails.

send_rpy(content, size, msg_no)

Allows to send a reply message (frame type RPY) to a message received (frame type MSG) with the provided msg_no.

Parameters:
  • content (String (may contain binary data like 0)) – The content to send.
  • size (Integer) – The content size or -1 to let the function to deduce string size. In the case you work with unicode strings, you use use -1 to let the method to deduce the right size because API requires byte-length while python provides the char length.
  • msg_no (Integer > 0) – The frame msgno that identifies the frame MSG we are replying
Return type:

Returns True if the reply operation was done, otherwise False is returned.

send_rpy_more(content, size, msg_no)

Allows to send a reply message (frame type RPY) to a message received (frame type MSG) with the provided msg_no, flagging all frames with more flag on.

Parameters:
  • content (String (may contain binary data like 0)) – The content to send.
  • size (Integer) – The content size or -1 to let the function to deduce string size. In the case you work with unicode strings, you use use -1 to let the method to deduce the right size because API requires byte-length while python provides the char length.
  • msg_no (Integer > 0) – The frame msgno that identifies the frame MSG we are replying
Return type:

Returns True if the reply operation was done, otherwise False is returned.

send_err(content, size, msg_no)

Allows to send an error reply message (frame type ERR) to a message received (frame type MSG) with the provided msg_no.

Parameters:
  • content (String (may contain binary data like 0)) – The content to send.
  • size (Integer) – The content size or -1 to let the function to deduce string size. In the case you work with unicode strings, you use use -1 to let the method to deduce the right size because API requires byte-length while python provides the char length.
  • msg_no (Integer > 0) – The frame msgno that identifies the frame MSG we are replying
Return type:

Returns True if the reply operation was done, otherwise False is returned.

send_err_more(content, size, msg_no)

Allows to send an error reply message (frame type ERR) to a message received (frame type MSG) with the provided msg_no, flagging all frames with more flag on.

Parameters:
  • content (String (may contain binary data like 0)) – The content to send.
  • size (Integer) – The content size or -1 to let the function to deduce string size. In the case you work with unicode strings, you use use -1 to let the method to deduce the right size because API requires byte-length while python provides the char length.
  • msg_no (Integer > 0) – The frame msgno that identifies the frame MSG we are replying
Return type:

Returns True if the reply operation was done, otherwise False is returned.

send_ans(content, size, msg_no)

Allows to send a reply message (frame type ANS) to a message received (frame type MSG) with the provided msg_no.

Parameters:
  • content (String (may contain binary data like 0)) – The content to send.
  • size (Integer) – The content size or -1 to let the function to deduce string size. In the case you work with unicode strings, you use use -1 to let the method to deduce the right size because API requires byte-length while python provides the char length.
  • msg_no (Integer > 0) – The frame msgno that identifies the frame MSG we are replying
Return type:

Returns True if the reply operation was done, otherwise False is returned.

finalize_ans(msg_no)

Finish an ANS exchange with the last NUL frame (created by this method).

Parameters:msg_no (Integer > 0) – The frame msgno that identifies the frame MSG we are replying with the last NUL.
Return type:Returns True if the reply operation was done, otherwise False is returned.
set_frame_received([handler][, data])

Allows to configure the frame received handler (the method or function that will be called for each frame received over this channel). The frame handler must have the following signature:

def frame_received (conn, channel, frame, data):
    # handle frame received
    return

Note if the method is called without argument it is assumed as a request to remove any previously configured handler.

Parameters:
  • handler (Frame received handler.) – The handler to configure
  • data (Object) – User defined data passed to the frame received handler.
set_complete_flag(flag)

Allows to configure if the channel should join all frames together into a single frame before delivering. By default, complete frames are delivered.

Parameters:flag (Boolean) – Complete flag value, True to make vortex to join fragments received together into a single frame or False to deliver all frames as received.
set_complete_frame_limit([frame_limit])

If complete_flag is enabled (see channel.set_complete_flag) this function allows to configure the limit beyond where the connection is completed if exceeded. By default, limit is disabled. After setting a limit, you can remove it by calling with limit set 0 or without any parameter.

Parameters:frame_limit (Number) – By default 0. If provided a value, it will be used as a frame size limit.
get_reply(queue)

This method is used as part of the queue reply method. It receives the queue configured along with vortex.queue_reply method as frame received. Calling to this method will block the caller until a frame is received.

The following is an example of queue reply method:

# configure frame received handler
queue = vortex.AsyncQueue ()
channel.set_frame_received (vortex.queue_reply, queue)

# wait for the reply
while True:
    frame = channel.get_reply (queue)

    # frame content received
    print ("Received frame type: " + frame.type + ", content: " + frame.payload)
Parameters:handler (vortex.AsyncQueue) – The queue that was activated with vortex.queue_reply (as Frame received handler)
Return type:Returns next frame received (vortex.Frame) or None if it fails
close()

Allows to request close the channel. The function will issue a close request that must be accepted by remote BEEP peer.

Return type:Returns True if the channel was closed, otherwise False is returned. In the case false is returned you can use Connection.pop_channel_error().
incref()

Allows to increment python reference count. This is used in cases where the channel reference is automatically collected by python GC but the VortexChannel reference that it was representing is still working (and may receive notifications, like frame received). Note that a call to this method, requires a call to decref().

decref()

Allows to decrement python reference count. See incref() for more information.

number

(Read only attribute) (Number) returns the channel number.

profile

(Read only attribute) (String) returns the channel profile.

is_ready

(Read only attribute) (True/False) returns is ready status. See vortex_channel_is_ready for more information.

conn

(Read only attribute) (vortex.Connection) returns a reference to the connection where the channel is working.

set_serialize

(Write only attribute) (True/False) Allows to configure channel delivery serialization. See also vortex_channel_set_serialize.