liblogging: beepframe.c File Reference

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

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