beepframe.h File Reference

The BEEP frame object. More...

#include "beepmessage.h"
#include "beepchannel.h"

Go to the source code of this file.

Compounds
struct	sbFramObject
	The BEEP frame object. More...
Defines
#define	__LIB3195_BEEPFRAME_H_INCLUDED__   1
#define	sbFramCHECKVALIDOBJECT(x)   {assert(x != NULL); assert(x->OID == OIDsbFram);}
Typedefs
typedef enum sbFramState_	sbFramState
typedef sbFramObject	sbFramObj
Enumerations
enum	sbFramState_ {   sbFRAMSTATE_WAITING_HDR1, sbFRAMSTATE_WAITING_HDR2, sbFRAMSTATE_WAITING_HDR3, sbFRAMSTATE_WAITING_SP_CHAN,   sbFRAMSTATE_IN_CHAN, sbFRAMSTATE_WAITING_SP_MSGNO, sbFRAMSTATE_IN_MSGNO, sbFRAMSTATE_WAITING_SP_MORE,   sbFRAMSTATE_IN_MORE, sbFRAMSTATE_WAITING_SP_SEQNO, sbFRAMSTATE_IN_SEQNO, sbFRAMSTATE_WAITING_SP_SIZE,   sbFRAMSTATE_IN_SIZE, sbFRAMSTATE_WAITING_SP_ANSNO, sbFRAMSTATE_IN_ANSNO, sbFRAMSTATE_WAITING_SP_ACKNO,   sbFRAMSTATE_IN_ACKNO, sbFRAMSTATE_WAITING_SP_WINDOW, sbFRAMSTATE_IN_WINDOW, sbFRAMSTATE_WAITING_HDRCR,   sbFRAMSTATE_WAITING_HDRLF, sbFRAMSTATE_IN_PAYLOAD, sbFRAMSTATE_WAITING_END1, sbFRAMSTATE_WAITING_END2,   sbFRAMSTATE_WAITING_END3, sbFRAMSTATE_WAITING_END4, sbFRAMSTATE_WAITING_END5, sbFRAMSTATE_RECEIVED,   sbFRAMSTATE_BEING_BUILD, sbFRAMSTATE_READY_TO_SEND, sbFRAMSTATE_SENDING, sbFRAMSTATE_SENT,   sbFRAMSTATE_UNKNOWN = 0 }
	Session status. More...
Functions
char *	sbFramGetFrame (sbFramObj *pThis)
	return frame content
int	sbFramGetFrameLen (sbFramObj *pThis)
	return length of frame
BEEPHdrID	sbFramGetHdrID (sbFramObj *pThis)
	Returns the header id of this BEEP frame.
srRetVal	sbFramDestroy (sbFramObj *pThis)
	destroy a frame object
sbFramObj *	sbFramCreateFramFromMesg (sbChanObj *pChan, sbMesgObj *pMesg, char *pszCmd, SBansno uAnsno)
	Create a frame from a Message.
sbFramObj *	sbFramActualRecvFram (sbSessObj *pSess)
	Actually receive a frame off the tcp stream.
sbFramObj *	sbFramRecvFram (sbChanObj *pChan)
	Logically receive a frame.
srRetVal	sbFramSendFram (sbFramObj *pThis, sbChanObj *pChan)
	Send a frame on a channel (logical).
BEEPHdrID	sbFramHdrID (char *szCmd)
	Get the header ID for a given BEEP command header.
srRetVal	sbFramConstruct (sbFramObj **ppThis)
	Construct a frame.
srRetVal	sbFramCreateSEQFram (sbFramObj **ppThis, sbChanObj *pChan, SBackno uAckno, SBwindow uWindow)
	Construct a SEQ frame for a given channel with a given ackno.
srRetVal	sbFramSetOnDestroyEvent (sbFramObj *pThis, void(*OnFramDestroy)(struct sbFramObject *), void *pUsr)
	Register a callback handler to be called when the frame is sent and ready to be destroyed.

---

Detailed Description

The BEEP frame object.

Note:

There are frames not belonging to messages! Curently, this is the case for SEQ frames defined in RFC 3081.

Author:

Rainer Gerhards <rgerhards@adiscon.com>

Date:

2003-08-04

Copyright 2002-2003 Rainer Gerhards and Adiscon GmbH. All Rights Reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of Adiscon GmbH or Rainer Gerhards nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

Enumeration Type Documentation

enum sbFramState_

Session status. Enumeration values: sbFRAMSTATE_WAITING_HDR1  waiting for the first HDR character sbFRAMSTATE_WAITING_HDR2  waiting for the second HDR character sbFRAMSTATE_WAITING_HDR3  waiting for the third HDR character sbFRAMSTATE_WAITING_SP_CHAN  waiting for the SP before channo sbFRAMSTATE_IN_CHAN  reading channo sbFRAMSTATE_WAITING_SP_MSGNO  now the space before the next header sbFRAMSTATE_IN_MSGNO  and the next (numeric) header sbFRAMSTATE_WAITING_SP_MORE  now the space before the next header sbFRAMSTATE_IN_MORE  and the next (char) header sbFRAMSTATE_WAITING_SP_SEQNO  now the space before the next header sbFRAMSTATE_IN_SEQNO  and the next (numeric) header sbFRAMSTATE_WAITING_SP_SIZE  now the space before the next header sbFRAMSTATE_IN_SIZE  and the next (numeric) header sbFRAMSTATE_WAITING_SP_ANSNO  now the space before the next header sbFRAMSTATE_IN_ANSNO  and the next (numeric) header sbFRAMSTATE_WAITING_SP_ACKNO  now the space before the next header sbFRAMSTATE_IN_ACKNO  and the next (char) header sbFRAMSTATE_WAITING_SP_WINDOW  now the space before the next header sbFRAMSTATE_IN_WINDOW  and the next (numeric) header sbFRAMSTATE_WAITING_HDRCR  awaiting the HDR's CR sbFRAMSTATE_WAITING_HDRLF  awaiting the HDR's LF sbFRAMSTATE_IN_PAYLOAD  reading payload area sbFRAMSTATE_WAITING_END1  waiting for the 1st HDR character sbFRAMSTATE_WAITING_END2  waiting for the 2nd HDR character sbFRAMSTATE_WAITING_END3  waiting for the 3rd HDR character sbFRAMSTATE_WAITING_END4  waiting for the 4th HDR character sbFRAMSTATE_WAITING_END5  waiting for the 5th HDR character sbFRAMSTATE_RECEIVED  frame is fully received and ready for processing sbFRAMSTATE_BEING_BUILD  frame is currently being constructed sbFRAMSTATE_READY_TO_SEND  frame is constructed and ready to send sbFRAMSTATE_SENDING  frame is currently being send sbFRAMSTATE_SENT  frame has been send and can be discarded sbFRAMSTATE_UNKNOWN  should never happen Set after initialization.

---

Function Documentation

sbFramObj* sbFramActualRecvFram (  sbSessObj *  pSess  )

Actually receive a frame off the tcp stream. Be sure to read architecture::c for a full explanation of what ActualRecvFram and its associated methods do in an overall context. In detail, it receives a frame off the wire and returns the resulting farme object to its caller. It detects different frame formats (like SEQ frames). This is a BLOCKING method call. It blocks until the frame is complete or a timeout occurs. Parameters: pSess  pointer to session object. This session is to be used to receive the frame. Return values: pointer  to the received frame object or NULL, if an error occured.

srRetVal sbFramConstruct (  sbFramObj **  ppThis  )

Construct a frame. This builds the memory structure, only but does not do anything to actually populate it.

sbFramObj* sbFramCreateFramFromMesg (  sbChanObj *  pChan, sbMesgObj *  pMesg, char *  pszCmd, SBansno  uAnsno )

Create a frame from a Message. With the current implementation, there is a one-to-one relationship between fram and mesg, so this is faily simple ;) Parameters: pChan  [in/out] Channel object that this frame will be sent on. Is updated with new SEQ number. pMesg  [in] Pointer to the Mesg to be converted. This buffer must not be modified by Mesg after CreateFramFromMesg has been called! pszCmd  [in] HDR-Command ("ANS", "MSG", ...) to be used. uAnso  [in] if the HDR-Command is "ANS", this is the ansno to be used. Ignored with any other HDR-Command. Return values: Pointer  to a newly created Frame object or NULL if an error occured.

srRetVal sbFramCreateSEQFram (  sbFramObj **  ppThis, sbChanObj *  pChan, SBackno  uAckno, SBwindow  uWindow )

Construct a SEQ frame for a given channel with a given ackno. Parameters: pChan  Channel this SEQ is for. uAckno  ackno to use in the SEQ. Can not be 0. uWindow  Window to use in the SEQ. If 0, use BEEP default.

BEEPHdrID sbFramHdrID (  char *  szCmd  )

Get the header ID for a given BEEP command header. This is implemented in the sbFram object as sbFram ultimately creaetes the frames and thus the IDs. One could argue if a better place would be some util helper... Parameters: psz  [in] pointer to a BEEP header command ("MSG", ...) Return values: matching  header id

sbFramObj* sbFramRecvFram (  sbChanObj *  pChan  )

Logically receive a frame. This method uses the session object to do the physical receive. See architecture::c for a full description of this interaction. This is just a slim wrapper to hide the implementation details. Parameters: pChan  [in/out] associated channel Return values: pointer  to new frame object or NULL, if in error.

srRetVal sbFramSendFram (  sbFramObj *  pThis, sbChanObj *  pChan )

Send a frame on a channel (logical). This method does not directly put the data on the wire but calls the session object to initiate this. This sequence allows for limited multiprocessing inside the stack. Please see architecture::c for a full description. This is just a very thin layer in this release. Parameters: pChan  the associated channel (where the frame is to be sent).

srRetVal sbFramSetOnDestroyEvent (  sbFramObj *  pThis, void(*  OnFramDestroy)(struct sbFramObject *), void *  pUsr )

Register a callback handler to be called when the frame is sent and ready to be destroyed. If there was already a handler set, it is REPLACED with the new one. There is no "calling-queue" of multiple handlers. Parameters: OnFramDestroy  Pointer to Callback. Must not be NULL. Pointer  to user pointer (may be NULL)

---