Class Hierarchy   Class Index   Method Index  

CHMllpClient Class Reference

#include <CHMllpClient.h>

Detailed Description

This class can be used to implement a Lower Layer Protocol (LLP) TCP/IP client to connect to an LLP server.

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


Public Member Functions

 CHMllpClient ()
 Constructor.
virtual ~CHMllpClient ()
 Destructor.
CHMclientHandle GetHandle () const
 This method is part of the internal implementation of this class and should not be called.
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 IsConnected () const
 The status of the connection with the server.
void StopMessageLoop ()
 Send a quit message to the thread that the networking components are running on.
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 Connect (const char *Host, CHMint32 Port)
 Connect to the given host and port number.
void Disconnect ()
 Attempt to gracefully disconnect from the server.
void HardDisconnect ()
 Ungracefully disconnect without doing TCP/IP handshaking with the server.
void TransmitMessage (const char *Message)
 Send a message to the server, prefixed and postfixed by the current CHMllpClient::HeaderBlock and CHMllpClient::TrailerBlock characters.
virtual void OnConnected ()=0
 Fired when the connection is made with the server.
virtual void OnClosed ()=0
 Fired when the connection is closed.
virtual void OnMessageReceived (const char *Message)=0
 Fired when a message is received.
virtual void OnDataIgnored (const char *Data)=0
 Fired when data has been received that is not within the header and trailer block.
virtual void OnErrorReceived (const char *Description, CHMint32 Code)=0
 Fired when we have an error with the TCP/IP connection.

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

CHMllpClient::CHMllpClient (   ) 
 

Constructor.

virtual CHMllpClient::~CHMllpClient (   )  [virtual]
 

Destructor.

Member Function Documentation

void CHMllpClient::Connect (  const char *  Host,
CHMint32  Port
) 
 

Connect to the given host and port number.

Function requires a running message loop (see CHMllpClient::RunMessageLoop).

Blocking: Function does not block.
Events: If the connection succeeds, a CHMllpClient::OnConnected event results. If the connection fails, an CHMllpClient::OnErrorReceived event results, containing the error message indicating why the connect attempt has failed.

Parameters:
Host Host to connect to.
Port Port to connect to.

void CHMllpClient::Disconnect (   ) 
 

Attempt to gracefully disconnect from the server.

A graceful disconnect implies a shutdown to the write end of the connection, and reading all data until the peer issues a close to its write end.

Note that the peer may not actually close the write end of its connection (although this is rare), which results in the connection never receiving the close event to signify that the connection is closed. In this situation, it is recommended that CHMllpClient::HardDisconnect be called to close the connection.

Function requires a running message loop (see CHMllpClient::RunMessageLoop).

Blocking: Function does not block.
Events: If the close succeeds (the peer closes the connection), a CHMllpClient::OnClosed event results. If an error occurs during the close operation, an CHMllpClient::OnErrorReceived event results, containing the error message indicating why the close attempt has failed.

CHMclientHandle CHMllpClient::GetHandle (   )  const [inline]
 

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

void CHMllpClient::HardDisconnect (   ) 
 

Ungracefully disconnect without doing TCP/IP handshaking with the server.

If there is data pending on the network buffer to be sent, the peer will receive a reset on the connection if it attempts to read or write to the connection.

Blocking: Function blocks; upon returning, the connection is closed.
Events: None.

const char* CHMllpClient::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 stream and wrapping outgoing messages.

See also the CHMllpClient::SetHeaderBlock method.

CHMboolean CHMllpClient::IsConnected (   )  const
 

The status of the connection with the server.

Returns true if the client is currently connected with the server.

const char* CHMllpClient::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 CHMllpClient::OnClosed (   )  [pure virtual]
 

Fired when the connection is closed.

virtual void CHMllpClient::OnConnected (   )  [pure virtual]
 

Fired when the connection is made with the server.

virtual void CHMllpClient::OnDataIgnored (  const char *  Data  )  [pure virtual]
 

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

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 bad error.

Parameters:
Data The ignored data.

virtual void CHMllpClient::OnErrorReceived (  const char *  Description,
CHMint32  Code
)  [pure virtual]
 

Fired when we have an error with the TCP/IP connection.

The context of when this is received is often determined by a previous operation. The connection will always be closed once this event is received.

Parameters:
Description Description of the error.
Code Error code.

virtual void CHMllpClient::OnMessageReceived (  const char *  Message  )  [pure virtual]
 

Fired when a message is received.

Does not include the CHMllpClient::HeaderBlock and CHMllpClient::TrailerBlock characters.

Parameters:
Message The message received.

static void CHMllpClient::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 CHMllpClient::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 CHMllpClient::SetHeaderBlock (  const char *  Value  ) 
 

Set method for headerBlock.

See CHMllpClient::HeaderBlock.

Parameters:
Value Value to set headerBlock to.

void CHMllpClient::SetTrailerBlock (  const char *  Value  ) 
 

Set method for trailerBlock.

See CHMllpClient::TrailerBlock.

Parameters:
Value Value to set trailerBlock to.

void CHMllpClient::StopMessageLoop (   ) 
 

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 CHMllpClient::RunMessageLoop method.

const char* CHMllpClient::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 stream and wrapping outgoing messages.

See also the CHMllpClient::SetTrailerBlock method.

void CHMllpClient::TransmitMessage (  const char *  Message  ) 
 

Send a message to the server, prefixed and postfixed by the current CHMllpClient::HeaderBlock and CHMllpClient::TrailerBlock characters.

The data is not guaranteed to be received after this function is called. All data is buffered internally; completion of this call does not signify reception of data.

Function requires a running message loop (see CHMllpClient::RunMessageLoop).

Blocking: Function does not block.
Events: If an error occurs during the send operation an CHMllpClient::OnErrorReceived event results, containing the error message indicating why the send attempt has failed.

Parameters:
Message Message to send to the server.

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