Class Hierarchy   Class Index   Method Index  

CHMllpServer Class Reference

#include <CHMllpServer.h>

Detailed Description

This object implements a Lower Layer Protocol (LLP) TCP/IP server that listens for connections from clients.

Most of the network events that are raised provide a CHMllpConnection parameter, which gives methods to interact with the client connection that the event is associated with.

See http://www.interfaceware.com/manual/network_components.html for more information.


Public Member Functions

 CHMllpServer ()
 Constructor.
virtual ~CHMllpServer ()
 Destructor.
CHMlistenerHandle GetHandle () const
 This method is part of the internal implementation of this class and should not be called.
CHMint32 Port () const
 The port on which we are listening, set by the CHMllpServer::StartListen method.
const char * Host () const
 The local interface on which we are listening, used by the next call to the CHMllpServer::StartListen method.
void SetHost (const char *Value)
 Set method for host.
const char * HeaderBlock () const
 The characters that precede a message in a stream.
void SetHeaderBlock (const char *Value)
 Set method for headerBlock.
const char * TrailerBlock () const
 The characters that follow a message in a stream.
void SetTrailerBlock (const char *Value)
 Set method for trailerBlock.
CHMboolean IsListening () const
 The status of the listening state.
CHMllpConnection Client (CHMint32 ClientIndex) const
 Representation of the collection of remote Clients that are connected to this server.
CHMint32 CountOfClient () const
 Returns the total number of Clients.
void StopMessageLoop ()
 This will send a quit message to the thread that the networking components are running on.
void StartListen (CHMint32 Port)
 Attempt to listen on the supplied port for incoming client connections.
const char * MakeMessagePrintable (const char *InputString, const char *NewLine, CHMint32 MaximumLength)
 Make message printable by changing plain carriage return characters "\r" to carriage return and newline characters "\r\n".
void StopListen ()
 Stop the component from listening for new connections.
void DisconnectAllClients ()
 Stop listening on the port for new connections, and initiate a CHMllpConnection::Disconnect on all open connections.
virtual void OnErrorReceived (const char *ErrorMessage, CHMint32 Code)=0
 Fired when an issue occurs with the server socket itself rather than a specific client.
virtual void OnClientConnected (CHMllpConnection &Client)=0
 Fired when a connection is made to the server by a new client.
virtual void OnClientDisconnected (CHMllpConnection &Client)=0
 Fired when a client disconnects from the server, or a previous CHMllpConnection::Disconnect call on a Connection succeeds.
virtual void OnClientErrorReceived (CHMllpConnection &Client, const char *ErrorMessage, CHMint32 ErrorCode)=0
 Fired when a networking error occurs with a specific client connection.
virtual void OnMessageReceived (CHMllpConnection &Client, const char *Message)=0
 Fired each time we receive a message from a connected HL7 client.
virtual void OnDataIgnored (CHMllpConnection &Client, const char *Data)=0
 Fired when data has been received that is not within the header and trailer block envelope.

Static Public Member Functions

static void RunMessageLoop ()
 On Unix and Linux platforms events are dispatched using a loop based on the select function.

Constructor & Destructor Documentation

CHMllpServer::CHMllpServer (   ) 
 

Constructor.

virtual CHMllpServer::~CHMllpServer (   )  [virtual]
 

Destructor.

Member Function Documentation

CHMllpConnection CHMllpServer::Client (  CHMint32  ClientIndex  )  const
 

Representation of the collection of remote Clients that are connected to this server.

This list changes in size as connections are received or closed, or if an error occurs on the connection (which implies a close).

Users cannot change the size or append to the contents of this collection since it is managed internally.

References to CHMllpConnection objects within this collection should not be maintained. Instead, always access CHMllpConnection objects through this collection interface, or the event to which CHMllpConnection objects are passed as parameters.

Parameters:
ClientIndex The index of the Client to return.

CHMint32 CHMllpServer::CountOfClient (   )  const
 

Returns the total number of Clients.

See also the CHMllpServer::Client property.

void CHMllpServer::DisconnectAllClients (   ) 
 

Stop listening on the port for new connections, and initiate a CHMllpConnection::Disconnect on all open connections.

This function requires a running message loop (see CHMllpServer::RunMessageLoop).

Blocking: Function blocks until CHMllpConnection::Disconnect is called on all open connections. This implies that the connections are not necessarily closed when this function returns.
Events: None.

CHMlistenerHandle CHMllpServer::GetHandle (   )  const [inline]
 

This method is part of the internal implementation of this class and should not be called.

const char* CHMllpServer::HeaderBlock (   )  const
 

The characters that precede a message in a stream.

The default value for this property is 0x0B as defined by the the LLP protocol.

This property is used both for parsing out the incoming data streams and wrapping outgoing messages.

See also the CHMllpServer::SetHeaderBlock method.

const char* CHMllpServer::Host (   )  const
 

The local interface on which we are listening, used by the next call to the CHMllpServer::StartListen method.

The default is an empty string, which means the listener will listen on all local interfaces.

It must be in the Internet standard "." (dotted) notation (e.g. 127.0.0.1).

See also the CHMllpServer::SetHost method.

CHMboolean CHMllpServer::IsListening (   )  const
 

The status of the listening state.

Returns true if the server is currently listening for connections.

Blocking: Function blocks until the listening state is determined.
Events: None.

const char* CHMllpServer::MakeMessagePrintable (  const char *  InputString,
const char *  NewLine,
CHMint32  MaximumLength
) 
 

Make message printable by changing plain carriage return characters "\r" to carriage return and newline characters "\r\n".

HL7 messages use the carriage return character "\r" to separate the segments. This makes it difficult to print them out in console windows because the cursor overwrites each previous segment instead of moving on to a newline for each segment. This method is intended to be a simple utility method to make it easier to convert HL7 messages into a printable format. This function also allows the output string to be truncated.

Parameters:
InputString Input message string.
NewLine Line feed string.
MaximumLength Maximum length of the message to print out. Characters after this length will be truncated. If you want to output the whole message, set the length to -1.
Returns:
Printable string, with "\r" characters changed to "\r\n"

virtual void CHMllpServer::OnClientConnected (  CHMllpConnection &  Client  )  [pure virtual]
 

Fired when a connection is made to the server by a new client.

This event is useful for logging.

Parameters:
Client The client object that is connecting.

virtual void CHMllpServer::OnClientDisconnected (  CHMllpConnection &  Client  )  [pure virtual]
 

Fired when a client disconnects from the server, or a previous CHMllpConnection::Disconnect call on a Connection succeeds.

This event is useful for logging.

Parameters:
Client The client object that is disconnecting.

virtual void CHMllpServer::OnClientErrorReceived (  CHMllpConnection &  Client,
const char *  ErrorMessage,
CHMint32  ErrorCode
)  [pure virtual]
 

Fired when a networking error occurs with a specific client connection.

The context on when this is received is often determined by a previous operation, although that is not necessary. The connection will always be closed once this event is received so there is no need to close the connection within the application code.

Parameters:
Client The client that had an error.
ErrorMessage The description of the error.
ErrorCode The code that describes the error.

virtual void CHMllpServer::OnDataIgnored (  CHMllpConnection &  Client,
const char *  Data
)  [pure virtual]
 

Fired when data has been received that is not within the header and trailer block envelope.

This is for dealing with an incorrect LLP implementation. The data is provided to the user's application through this event. This allows it to be logged since this is likely to be a very significant error with the counterparty's LLP implementation.

Parameters:
Client The client that has sent the data.
Data Data in string format that has been sent.

virtual void CHMllpServer::OnErrorReceived (  const char *  ErrorMessage,
CHMint32  Code
)  [pure virtual]
 

Fired when an issue occurs with the server socket itself rather than a specific client.

Parameters:
ErrorMessage A message describing the error.
Code A code describing the error.

virtual void CHMllpServer::OnMessageReceived (  CHMllpConnection &  Client,
const char *  Message
)  [pure virtual]
 

Fired each time we receive a message from a connected HL7 client.

Typically, the message should be processed and only then should an HL7 ACKnowledgement message be sent.

Received without any Trailer or Header characters.

Parameters:
Client The client that has sent the message.
Message The HL7 message (in string format) that has been sent.

CHMint32 CHMllpServer::Port (   )  const
 

The port on which we are listening, set by the CHMllpServer::StartListen method.

static void CHMllpServer::RunMessageLoop (   )  [static]
 

On Unix and Linux platforms events are dispatched using a loop based on the select function.

All POSIX applications require this function to be called in order to start receiving events.

On Windows platforms all events are dispatched using the Windows message loop.

Graphical Windows applications contain a running Windows message loop; therefore, this function will not need to be called. Console applications require this function to be called in order to start receiving events.

Throws: Function will throw an exception only if the operating system reports an error.
Blocking: Function will block until CHMllpServer::StopMessageLoop is called, or (Windows only) a WM_QUIT message is posted to the message loop on the thread that the networking components are running on.

void CHMllpServer::SetHeaderBlock (  const char *  Value  ) 
 

Set method for headerBlock.

See CHMllpServer::HeaderBlock.

Parameters:
Value Value to set headerBlock to.

void CHMllpServer::SetHost (  const char *  Value  ) 
 

Set method for host.

See CHMllpServer::Host.

Parameters:
Value Value to set host to.

void CHMllpServer::SetTrailerBlock (  const char *  Value  ) 
 

Set method for trailerBlock.

See CHMllpServer::TrailerBlock.

Parameters:
Value Value to set trailerBlock to.

void CHMllpServer::StartListen (  CHMint32  Port  ) 
 

Attempt to listen on the supplied port for incoming client connections.

This function requires a running message loop (see CHMllpServer::RunMessageLoop) in order to receive connections.

Blocking: Function blocks until a port can be successfully listened on or an error occurs.
Throws: Function will throw an exception if the port is in use, or the operating system reports any other error.
Events: None.

By default, the listener will listen on all local interfaces. To make it listen on a specific local interface use the CHMllpServer::Host property to set the IP address of the interface to use.

Parameters:
Port Port to listen on.

void CHMllpServer::StopListen (   ) 
 

Stop the component from listening for new connections.

Note that any existing connections that have already been established are NOT closed. In order to properly disconnect existing connections as well as stop listening, use CHMllpServer::DisconnectAllClients.

Blocking: Function blocks until the stop listen succeeds.
Throws: Function does not throw any exceptions.
Events: None.

void CHMllpServer::StopMessageLoop (   ) 
 

This will send a quit message to the thread that the networking components are running on.

Under Windows, this is a WM_QUIT message. All the networking components must be created on a single thread with a running message loop. For more information, see the CHMllpServer::RunMessageLoop method.

const char* CHMllpServer::TrailerBlock (   )  const
 

The characters that follow a message in a stream.

The default value is the character 0x1C followed by 0x0D as defined by the LLP protocol.

This property is used both for parsing out the incoming data streams and wrapping outgoing messages.

See also the CHMllpServer::SetTrailerBlock method.

The documentation for this class was generated from the following file: