beepframe.c File Reference

Implementation of the BEEP Frame object. More...

#include <assert.h>
#include "config.h"
#include "liblogging.h"
#include "sockets.h"
#include "beepmessage.h"
#include "beepframe.h"
#include "beepchannel.h"
#include "beepsession.h"

Functions
unsigned	sbFramRecvUnsigned (sbSockObj *pSock)
	Receive an unsigned integer from the channel.
srRetVal	sbFramActualRecvFramSEQ (sbFramObj *pThis, sbChanObj *pChan)
	Helper to sbFramActualRecvFram; receives an SEQ frame off the wire.
srRetVal	sbFramActualRecvFramCommonHdr (sbFramObj *pThis, sbChanObj *pChan)
	Helper to sbFramActualRecvFramAns and *Normal; receives the common header off the wire.
	sbFramActualRecvFramCommonBody (sbFramObj *pThis, sbChanObj *pChan)
	Helper to sbFramActualRecvFramAns and *Normal; receives the common body off the wire.
srRetVal	sbFramActualRecvFramANS (sbFramObj *pThis, sbChanObj *pChan)
	Helper to sbFramActualRecvFram; receives an ANS frame off the wire.
srRetVal	sbFramActualRecvFramNormal (sbFramObj *pThis, sbChanObj *pChan)
	Helper to sbFramActualRecvFram; receives a normal (that is non-SEQ and non-ANS) frame off the wire.
BEEPHdrID	sbFramHdrID (char *szCmd)
	Get the header ID for a given BEEP command header.
srRetVal	sbFramConstruct (sbFramObj **ppThis)
	Construct a frame.
BEEPHdrID	sbFramGetHdrID (sbFramObj *pThis)
	Returns the header id of this BEEP frame.
int	sbFramGetFrameLen (sbFramObj *pThis)
	return length of frame
char *	sbFramGetFrame (sbFramObj *pThis)
	return frame content
sbFramObj *	sbFramCreateFramFromMesg (sbChanObj *pChan, sbMesgObj *pMesg, char *pszCmd, SBansno uAnsno)
	Create a frame from a Message.
srRetVal	sbFramCreateSEQFram (sbFramObj **ppThis, sbChanObj *pChan, SBackno uAckno, SBwindow uWindow)
	Construct a SEQ frame for a given channel with a given ackno.
sbFramObj *	sbFramActualRecvFram (sbSessObj *pSess)
	Actually receive a frame off the tcp stream.
srRetVal	sbFramDestroy (sbFramObj *pThis)
	destroy a frame object
sbFramObj *	sbFramRecvFram (sbChanObj *pChan)
	Logically receive a frame.
srRetVal	sbFramSendFram (sbFramObj *pThis, sbChanObj *pChan)
	Send a frame on a channel (logical).
srRetVal	sbFramSetOnDestroyEvent (sbFramObj *pThis, void(*OnFramDestroy)(sbFramObj *), void *pUsr)

---

Detailed Description

Implementation of the BEEP Frame object.

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.

---

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 sbFramActualRecvFramANS (  sbFramObj *  pThis, sbChanObj *  pChan )

Helper to sbFramActualRecvFram; receives an ANS frame off the wire. Parameters: pThis  [in/out] frame object to be filled. This is partly created by the caller. new properties read by this function are filled in. We do it that way so that we can e.g. do error checking for calloc() failures only in the caller. Saves us some code ;) pChan  [in/out] the channel to receive the frame on. The channel object is updated, e.g. with a new seqno.

sbFramActualRecvFramCommonBody (  sbFramObj *  pThis, sbChanObj *  pChan )

Helper to sbFramActualRecvFramAns and *Normal; receives the common body off the wire. The body is defined to start WITH the CRLF in the header. As such, this method processes the header CRLF payload trailer Parameters: pThis  [in/out] frame object to be filled. This is partly created by the caller. new properties read by this function are filled in. We do it that way so that we can e.g. do error checking for calloc() failures only in the caller. Saves us some code ;) pChan  [in/out] the channel to receive the frame on. The channel object is updated, e.g. with a new seqno.

srRetVal sbFramActualRecvFramCommonHdr (  sbFramObj *  pThis, sbChanObj *  pChan )

Helper to sbFramActualRecvFramAns and *Normal; receives the common header off the wire. Parameters: pThis  [in/out] frame object to be filled. This is partly created by the caller. new properties read by this function are filled in. We do it that way so that we can e.g. do error checking for calloc() failures only in the caller. Saves us some code ;) pChan  [in/out] the channel to receive the frame on. The channel object is updated, e.g. with a new seqno. Todo: improve!

srRetVal sbFramActualRecvFramNormal (  sbFramObj *  pThis, sbChanObj *  pChan )

Helper to sbFramActualRecvFram; receives a normal (that is non-SEQ and non-ANS) frame off the wire. Parameters: pThis  [in/out] frame object to be filled. This is partly created by the caller. new properties read by this function are filled in. We do it that way so that we can e.g. do error checking for calloc() failures only in the caller. Saves us some code ;) pChan  [in/out] the channel to receive the frame on. The channel object is updated, e.g. with a new seqno.

srRetVal sbFramActualRecvFramSEQ (  sbFramObj *  pThis, sbChanObj *  pChan )

Helper to sbFramActualRecvFram; receives an SEQ frame off the wire. See RFC 3081, 3.1.3 for the semantics of a SEQ frame. Parameters: pThis  [in/out] frame object to be filled. This is partly created by the caller. new properties read by this function are filled in. We do it that way so that we can e.g. do error checking for calloc() failures only in the caller. Saves us some code ;) pChan  [in/out] the channel to receive the frame on. The channel object is updated, e.g. with a new seqno.

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.

unsigned sbFramRecvUnsigned (  sbSockObj *  pSock  )

Receive an unsigned integer from the channel. Eats up characters as it processes them. Return values: integer  receive. If there are no digits immediately in the input stream, 0 is returned and no character is taken from the input stream.

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

---