NAME

Net::BEEP::Lite::Session

DESCRIPTION

This is a base class for BEEP sessions. It handles core tasks common to both server and client sessions. This class isn't intended to be used directly. Instead, use one of its subclasses.

Note that in reality, this is really a TCP session. It is not abstracted away from the TCP transport for BEEP. In the future it is possible that it will be and a new TCPSession subclass will be created.

CONSTRUCTOR

new( ARGS )

This is the main constructor. It takes a named parameter list as its argument. See the initialize method for a list of valid parameter names.

METHODS

initialize( ARGS )

Initialize the object. This is generally called by the constructor and subclasses. It takes the following named parameters:

Socket

the socket associated with this session.

NoGreeting

Do not send the greeting message. This can be sent later with the send_greeting method. This will be true if a socket isn't supplied.

It also takes the named parameters for Net::BEEP::Lite::MgmtProfile.

socket()

Returns the internal socket.

_set_socket($socket)

Change the session's internal socket to the supplied socket. Only use this if you know what you are doing.

_next_channel_number()

This returns the next channel number to request.

_add_channel($channel_number, [$profile, [$local_window_size]])

This is called by the management profile upon receiving a <start> or <profile> message from the peer. If $profile is provided, then this will bind that profile to the channel.

_del_channel($channel_number)

This is called by profiles when it needs to close a channel (either a close request on the channel or a tuning reset (see _del_all_channels).

_del_all_channels()

Close (and destroy) all current channels. This is most likely to be done as part of a tuning reset. You will have to re-add channel zero after this.

add_local_profile($profile)

This method will add a (local) profile to the session. This will be advertised in the greeting message.

get_local_profile($uri)

Returns the profile implementation associated with the given uri.

get_local_profile_uris()

Returns the list of profile URIs currently being advertised by this peer.

del_local_profile($uri)

Removes a local profile.

add_remote_profile($uri)

This method is used internally when the remote peer advertises a profile in the greeting message.

has_remote_profile($uri)

This method returns true if the remote profile advertised the given profile uri, false otherwise.

remote_profiles()

This method returns a list of the peer's advertised profiles.

num_open_channels()

Return the number of open channels associated with this session. This does not include channel zero.

channel($channel_number)

Returns the Net::BEEP::Lite::Channel object for the given channel number.

servername([$val])

Returns or sets the session's server name. This is normally set when the first "<start>" message is encountered with a "serverName" attribute.

_tuning_reset([$send_greeting])

This does the full tuning reset: close all channels, delete pending messages in the message queue, recreate channel zero, and (optionally) re-send the greeting. This defaults to sending the greeting.

This is normally called when a profile negotiates a security layer (i.e., TLS or maybe SASL/DIGEST-MD5's encryption).

send_greeting()

Send the greeting message to the peer, and handle the greeting coming from the peer. It will advertise any profiles that have been configured in the session. Normally, this method is called as part of the initialization process of the subclasses of this class.

send_message($message)

This will send a BEEP message to the peer (over the channel specified in the message). This will handle possible fragmentation due to the channel window size.

_recv_message()

This will fetch the next message from the peer, returning a message object. It will handle reassembling a fragmented message. It will return the first complete message received on any (existing) channel. It will discard frames on non-existent channels, issuing a warning.

This method will block. It will return undef if it is not possible to read from the socket, otherwise it will return the message.

recv_message()

This will fetch the next message (on any defined channel other than zero) from the peer, returning a message object. It will handle reassembling a fragmented message. This will directly handle channel zero messages, so this isn't all that useful for handling replies to management channel messages.

close_session()

close the entire session. Normally, this should only be called after sending or receiving the "<ok>" message. It can also be used in fatal error situations.

_read_for_seq([$channel_number])

Read frames from the socket until receiving a SEQ frame. If $channel_number is provided, then read until a SEQ frame on that channel has been read. Non SEQ frames read are place either in the various message-building slots (see _recv_message), or place on the general message queue.

_recv_frame()

This is an intermediate wrapper around _read_frame. Essentially, it reads a frame from the socket, then does a little bit of post processing, finally returning that frame. The processing is: if it is a SEQ frame, it updates the channels remote window size accordingly; if it is some other frame, it adds it to the appropriate channel's message building slot.

It returns undef if the socket could not be read from. It returns 0 if the frame was on a non-existent channel.

_send_seq($channel, $ackno)

Send a SEQ for $channel_number to the peer. $ackno is the sequence number to acknowledge. Generally this is the seqno of the frame this is responding to, plus the size of the payload of that frame.

_read_frame()

This is an internal method for reading a single frame from the internal socket. It returns a Net::BEEP::Lite::Frame object.

_write_frame($frame)

This is an internal routine for writing a single frame to the internally held socket. $frame MUST be a Net::BEEP::Lite::Frame object.

SEE-ALSO

Net::BEEP::Lite::ServerSession

Net::BEEP::Lite::ClientSession

Net::BEEP::Lite::Message

Net::BEEP::Lite::Frame