Main Page | Compound List | File List | Compound Members | File Members | Related Pages

# 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)