The Network Kit: BStandardPacket

Derived from: BNetPacket

Declared in: be/addons/net_server/NetPacket.h

Library: libnetdev.so


Overview

The pure abstract class BNetPacket defines a network packet in the most generic possible terms. In fact, it's so generic that you have to implement your own derived class to actually manipulate network packets.

The BStandardPacket class is provided as a default BNetPacket-derived class that you can use in many cases; unlike the BNetPacket class, BStandardPacket provides useful implementations of its member functions (BNetPacket implements only the Read() and Write() functions, which are useless without the other functions being implemented as well), so this is often a better starting place than BNetPacket itself.

For a more detailed view into the lives and loves of network packets, read the BNetPacket section.


Constructor and Destructor


BStandardPacket()


      BStandardPacket(unsigned size = 0)

Constructs a new BStandardPacket object, which can contain data of up to size bytes.

Packet sizes smaller than 1,536 bytes are handled slightly more efficiently by the BStandardPacket class.


~BStandardPacket()


      ~BStandardPacket(void)

Deallocates the packet data buffer and destroys the object.


Member Functions


Base(), SetBase()


      unsigned Base(void)

      void SetBase(int offset)

Base() returns the offset into the packet at which data is considered to begin. The value returned by this function is an absolute offset into the packet data.

The SetBase() function sets the base as an offset from the current base; to move the base forward 12 bytes, you would call:

   packet->SetBase(12);

To move the base backward 8 bytes, you would call:

   packet->SetBase(-8)

Together, these functions can be used to hide packet headers without actually stripping them out of the packets. Note that changing the base offset also affects the value returned by Size(); adding 15 bytes to the base likewise reduces the size of the available data by 15 bytes (since the distance between the base and the end of the data has been reduced by 15 bytes).


DataBlock()


      char *DataBlock(unsigned offset, unsigned *size)

This function returns a pointer to the byte of data located at the specified offset into the packet's data. Keep in mind that the offset specified here is added to the current base offset.

Before calling DataBlock(), store the number of bytes you want to read in the size varaible. When the function returns, the value of size will be changed to the number of bytes actually available beginning at the returned address. The value of size will only change if there are fewer bytes left in the packet's data than you asked for.

If the offset would index out of the packet's data buffer, DataBlock() invokes the system debugger, so be sure you don't do that.


Read(), Write()


      void Read(unsigned offset, char *buffer, unsigned count)

      void Write(unsigned offset, const char *buffer, unsigned count)

Read() copies data from the specified offset in the packet's data to the address pointed to by buffer. Up to count bytes are copied. If count is larger than the number of bytes between offset and the end of the packet, then that portion of the packet is transferred.

Write() copies count bytes of data from the specified buffer to the specified offset in the packet data.

Again, keep in mind that the specified offset values are added to the current base offset before the read or write operation is performed.


SetSize(), Size()


      void SetSize(unsigned size)

      unsigned Size(void)

SetSize() lets the caller specify the size of the packet data that can be represented by the object. This call changes the number of bytes between the current base offset and the end of the packet data buffer.

The Size() function returns the current packet size--the number of bytes between the base offset and the end of the packet buffer.

Note that the size of the packet buffer will fluctuate as the base offset is moved around using the SetBase() function. The Size() and SetSize() functions manipulate the size of the data between the current base and the end of the packet buffer.






The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.