Database Stream Class

Topics:

The gxStream class is derived from the gxSocket class and is used to send and receive database blocks over a TCP connection.

Description: The 32/64-bit gxDatabase engine is used to construct multi-platform database files. Since its inception additional communication components have been added to the library to support TCP/IP communications via TCP and UDP sockets. The additional communication components are part of sub-library named the gxSocket Library. By adding gxSocket components to existing gxDatabase applications you can read and write database blocks over a local or wide are network in real-time. gxSocket applications use the network to allow database application to communicate with each. Database blocks are contiguous bytes of binary data marked with a block header. The block header contain a block check word, the size of the block, the block status, and a pointer to the next deleted block (applicable to disk files only). When a database block is allocated a new block header is constructed and written to the database file directly before the space allocated for the block data. Using the gxSocket library extensions the same block header written to a disked-based database can be used to transmit a database block to a remote host. By design, gxDatabase files use an internal format for byte ordering allowing block headers to work transparently in a multi-platform environment.

Protocol Number: TCP & UDP

Message Formats: Block check-word, block length, and status code

Message Types: Request, reply, acknowledge, shutdown

Message opcodes: Add block, change block, delete remote block, client request failed, close client/server connection, shutdown client/server, request block, send raw data, acknowledge block

Message Sequences: When a client sends a block of raw data a block header precedes the data and informs the server of the block size and the block status. After reception of a device header the server waits for the block data and processes the data or signals/handles an event according to the status of the block.

Protocol functions: Communication via database block headers allows gxDatabase applications to share database blocks in a client/server relationship.

Functions

gxStream::gxStream()
gxStream::~gxStream()
gxStream::AddBlock()
gxStream::ChangeBlock()
gxStream::CloseConnection()
gxStream::DeleteBlock()
gxStream::HostName()
gxStream::PortNumber()
gxStream::ReadAckBlock()
gxStream::ReadBlock()
gxStream::ReadClientHeader()
gxStream::ReadHeader()
gxStream::ReadRemoteAckBlock()
gxStream::ReadRemoteBlock()
gxStream::RemoteHostName()
gxStream::RemotePortNumber()
gxStream::RequestBlock()
gxStream::SetBlockStatus()
gxStream::StreamClient()
gxStream::StreamServer()
gxStream::TerminateConnection()
gxStream::WriteAckBlock()
gxStream::WriteBlock()
gxStream::WriteHeader()
gxStream::WriteRemoteAckBlock()
gxStream::WriteRemoteBlock()

gxStream::gxStream() - Default class constructor.

gxStream::~gxStream() - Class destructor.

int gxStream::AddBlock(const void *block, gxBlockHeader &block_header) - Public member function used to request that the block pointed to by the "block" variable be added by a local or remote device. The block header must account for the total length of the data pointed to by the "block" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::AddBlock(gxsSocket_t s, const void *block, gxBlockHeader &block_header) - Public member function used to request that the block pointed to by the "block" variable be added by the specified socket descriptor. The block header must account for the total length of the data pointed to by the "block" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::ChangeBlock(const void *request, const void *block, gxBlockHeader &request_header, gxBlockHeader &block_header) - Public member function used to request that the block pointed to by the "block" variable be changed by a local or remote device. The "request" variable points to the new information that will be inserted in place of the block pointed to by the "block" variable. The block header must account for the total length of the data pointed to by the "block" variable and the "request_header" must account for the total length of the data pointed to by the "request" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::ChangeBlock(gxsSocket_t s, const void *request, const void *block, gxBlockHeader &request_header,gxBlockHeader &block_header) - Public member function used to request that the block pointed to by the "block" variable be changed by the specified socket descriptor. The "request" variable points to the new information that will be inserted in place of the block pointed to by the "block" variable. The block header must account for the total length of the data pointed to by the "block" variable and the "request_header" must account for the total length of the data pointed to by the "request" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::CloseConnection() - Public member function that sends a block command used to close a persistent client or server connection. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::CloseConnection(gxsSocket_t s) - Public member function that sends a block command to the specified socket descriptor used to close a persistent client or server connection. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::DeleteBlock(const void *request, gxBlockHeader &request_header) - Public member function used to request that the a block pointed to by the "request" variable be deleted. The "request_header" must account for the total length of the data pointed to by the "request" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::DeleteBlock(gxsSocket_t s, const void *request,gxBlockHeader &request_header) - Public member function used to request that the a block pointed to by the "request" variable be deleted by the specified socket descriptor. The "request_header" must account for the total length of the data pointed to by the "request" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::HostName(char *hs) - Public member function that passes back the host name of this machine in the "hs" variable. NOTE: A memory buffer equal to gxsMAX_NAME_LEN must be pre-allocated prior to using this function. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::PortNumber(int &port) - Public member function that passes back the port number actually set by the system in the "port" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::ReadAckBlock() - Public member function used to read an acknowledgment block. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::ReadAckBlock(gxsSocket_t s) - Public member function used to read an acknowledgment block from the specified socket descriptor. Returns zero if no errors occurs or a non-zero value to indicate a failure.

int gxStream::ReadBlock(gxsSocket_t s, void *buf, gxBlockHeader &gx) - Public member function used to read a variable block from the specified socket descriptor. The block header must account for the total length of the data pointed to by the "buf" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::ReadClientHeader(gxBlockHeader &gxs) - Public member function used to read a client header. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::ReadHeader(gxsSocket_t s, gxBlockHeader &gx) - Public member function used to read a device block header from the specified socket descriptor. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::ReadRemoteAckBlock() - Public member function used to read a client acknowledgment block. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::ReadRemoteBlock(void *buf, gxBlockHeader &gx) - Public member function used to read a remote block. The block header must account for the total length of the data pointed to by the "buf" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::RemoteHostName(char *hs) - Public member function that passes back the host name of the client in the "hs" variable. NOTE: A memory buffer for "hs" equal to gxsMAX_NAME_LEN must be pre-allocated prior to using this function. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::RemotePortNumber(int &port) - Public member function that passes back the client's port number in the "port" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

void *gxStream::RequestBlock(const void *request, gxBlockHeader &request_header, gxBlockHeader &requested_block_header) - Public member function used to request a block from the remote end. The "request" variable points to the request information. The "request_header" must account for the total length of the data pointed to by the "request" variable. Returns the requested block or a null value if an error occurs. The block returned by this function must be typecast to the correct type by the calling function.

void *gxStream::RequestBlock(gxsSocket_t s, const void *request, gxBlockHeader &request_header,gxBlockHeader &requested_block_header) - Public member function used to request a block from the specified socket descriptor. The "request" variable points to the request information. The "request_header" must account for the total length of the data pointed to by the "request" variable. Returns the requested block or a null value if an error occurs. The block returned by this function must be typecast to the correct type by the calling function.

void gxStream::SetBlockStatus(gxBlockHeader &gx, __SBYTE__ net_status,__SBYTE__ file_status = gxRemoteDeviceBlock) - Public member function used to set the variable block header status member control byte. NOTE: The block's next deleted variable must be set, if needed, after a call to this function. The block length will not be set here.

int gxStream::StreamClient(int port, char *host) - Public member function used to connect a stream client to the specified host. Returns zero if no errors occur during initialization or a non-zero value to indicate a failure.

int gxStream::StreamServer(int port, int max_connections = SOMAXCONN) - Public member function used to initialize a stream server. Returns zero if no errors occur during initialization or a non-zero value to indicate a failure.

int gxStream::TerminateConnection() - Public member function used to send a block command that will shutdown a server or client. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::TerminateConnection(gxsSocket_t s) - Public member function used to send a block command to the specified socket descriptor that will shutdown a server or client. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::WriteAckBlock() - Public member function used to write an acknowledgment block. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::WriteAckBlock(gxsSocket_t s) - Public member function used to write an acknowledgment block to the specified socket descriptor. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::WriteBlock(const void *buf, int bytes) - Public member function used to write a block of raw data. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::WriteBlock(gxsSocket_t s, const void *buf, int bytes) - Public member function used to write a block of raw data to the specified socket descriptor. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::WriteBlock(gxsSocket_t s, const void *buf, gxBlockHeader &gx) -Public member function used to write a variable block to the specified socket descriptor. The block header must account for the total length of the data pointed to by the "buf" variable. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::WriteHeader(gxsSocket_t s, gxBlockHeader &gx) - Public member function used to write a block header to the specified socket descriptor. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::WriteRemoteAckBlock() - Public member function used to write an acknowledgment block to the remote end. Returns zero if no errors occur or a non-zero value to indicate a failure.

int gxStream::WriteRemoteBlock(void *buf, int bytes) - Public member function used to write a block of raw data to the remote end. Returns zero if no errors occur or a non-zero value to indicate a failure.

End Of Document