Class Hierarchy   Class Index   Method Index  

IGCdestination Class Reference

#include <IGCdestination.h>

Detailed Description

This class is used to implement an Iguana destination plugin.

Destination plugins connect to, and receive messages from Iguana To-Plugin channel components.

Messages are sent from Iguana to the IGCdestination plugin through the IGCdestination::OnMessageReceived event. The plugin must set properties on the IGCdestinationMessageReceivedEventOutputs object that will be passed to event handler. This will indicate to Iguana whether message processing was successful.

See:

http://www.interfaceware.com/manual/plugin_receiving.html

for more information.


Public Member Functions

 IGCdestination ()
 Constructor.
virtual ~IGCdestination ()
 Destructor.
IGCdestinationHandle GetHandle () const
 This method is part of the internal implementation of this class and should not be called.
IGCdisconnectReason DisconnectReason () const
 Describes the reason for the plugin's (most recent) disconnection from Iguana.
IGCint32 ConnectTimeout () const
 Time in milliseconds the plugin will wait to handshake with Iguana while executing the IGCdestination::Connect operation (default 5000 milliseconds).
void SetConnectTimeout (IGCint32 Value)
 Set method for ConnectTimeout.
void EnableDebugLogging (const char *FileName)
 Enables logging of internal runtime debug information to the specified file.
void Connect (const char *HostName, IGCint32 PortNumber, const char *ChannelName)
 Connects to an Iguana To-Plugin channel component as a destination plugin.
void Disconnect ()
 Disconnects the plugin from Iguana.
void WaitForDisconnect ()
 Waits until the plugin is disconnected from Iguana.
IGCboolean WaitForDisconnectWithTimeout (IGCint32 TimeoutInMilliseconds)
 Waits until either the plugin is disconnected from Iguana, or a specified timeout elapses.
virtual void OnMessageReceived (IGCdestinationMessageReceivedEventInputs &Inputs, IGCdestinationMessageReceivedEventOutputs &Outputs)=0
 Event raised upon receipt of a message from Iguana.
virtual void OnResubmissionPreviewMessageReceived (IGCdestinationMessageReceivedEventInputs &Inputs, IGCdestinationMessageReceivedEventOutputs &Outputs)=0
 Event raised upon receipt of a resubmission preview message from Iguana.
virtual void OnDisconnected ()=0
 Event raised upon disconnection of the plugin from Iguana.

Constructor & Destructor Documentation

IGCdestination::IGCdestination (   ) 
 

Constructor.

virtual IGCdestination::~IGCdestination (   )  [virtual]
 

Destructor.

Member Function Documentation

void IGCdestination::Connect (  const char *  HostName,
IGCint32  PortNumber,
const char *  ChannelName
) 
 

Connects to an Iguana To-Plugin channel component as a destination plugin.

Normally, this method is called as the plugin starts and is ready to receive data from Iguana or if Iguana has disconnected from the plugin (for example, after returning from a call to IGCdestination::WaitForDisconnect).

It may not be called from within an event handler (for example, may not be called from within the IGCdestination::OnDisconnected handler).

If a connection is not established within the timeout period specified by IGCdestination::ConnectTimeout, an exception will be thrown. The default timeout period of 5000 milliseconds should suffice for most plugins, and should only be adjusted if connection timeouts are observed.

One common point of confusion with users is the choice of port number for this call. This must be the port number for the Plugin Communication Server, which is typically 6123, not the LLP port for the particular plugin channel.

Throws: Function throws an exception upon connection failure or timeout, or if called from within an event handler.

Parameters:
HostName Iguana machine hostname or IP address (typically 'localhost' if the plugin and Iguana are running on the same machine).
PortNumber Iguana Plugin Communication Server port number (typically 6123).
ChannelName Iguana channel name.

IGCint32 IGCdestination::ConnectTimeout (   )  const
 

Time in milliseconds the plugin will wait to handshake with Iguana while executing the IGCdestination::Connect operation (default 5000 milliseconds).

For a heavily loaded Iguana server running on a slow machine this may need a higher value than the default value.

See also the IGCdestination::SetConnectTimeout method.

void IGCdestination::Disconnect (   ) 
 

Disconnects the plugin from Iguana.

Results in IGCdestination::DisconnectReason being set to DueToPlugin.

IGCdisconnectReason IGCdestination::DisconnectReason (   )  const
 

Describes the reason for the plugin's (most recent) disconnection from Iguana.

Only valid after the plugin has been disconnected, and before any subsequent connection attempts. Specifically, only valid within the IGCdestination::OnDisconnected handler or after the return of a call to IGCdestination::WaitForDisconnect or IGCdestination::WaitForDisconnectWithTimeout, and before any subsequent calls to IGCdestination::Connect.

void IGCdestination::EnableDebugLogging (  const char *  FileName  ) 
 

Enables logging of internal runtime debug information to the specified file.

Must be called before any other methods, and may only be called once per Destination instance.

This function should only be used at the request of iNTERFACEWARE Technical Support.

Parameters:
FileName Name of the file where debug information is to be logged.

IGCdestinationHandle IGCdestination::GetHandle (   )  const [inline]
 

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

virtual void IGCdestination::OnDisconnected (   )  [pure virtual]
 

Event raised upon disconnection of the plugin from Iguana.

Will not be raised for failed connection attempts. Specifically, will not be raised if IGCdestination::Connect throws an exception as a result of a connection failure.

Exceptions should never be allowed to propagate out of the event handler. Event handlers should catch and handle all exceptions internally.

virtual void IGCdestination::OnMessageReceived (  IGCdestinationMessageReceivedEventInputs &  Inputs,
IGCdestinationMessageReceivedEventOutputs &  Outputs
)  [pure virtual]
 

Event raised upon receipt of a message from Iguana.

Exceptions should never be allowed to propagate out of the event handler. Event handlers should catch and handle all exceptions internally.

Parameters:
Inputs Input data from Iguana.
Outputs Output data to send back to Iguana.

virtual void IGCdestination::OnResubmissionPreviewMessageReceived (  IGCdestinationMessageReceivedEventInputs &  Inputs,
IGCdestinationMessageReceivedEventOutputs &  Outputs
)  [pure virtual]
 

Event raised upon receipt of a resubmission preview message from Iguana.

Plugins should simulate the processing that would be performed by the IGCdestination::OnMessageReceived event handler without causing external side effects. For example, database changes should not be made for resubmission preview messages.

Exceptions should never be allowed to propagate out of the event handler. Event handlers should catch and handle all exceptions internally.

Parameters:
Inputs Input data from Iguana.
Outputs Output data to send back to Iguana.

void IGCdestination::SetConnectTimeout (  IGCint32  Value  ) 
 

Set method for ConnectTimeout.

See IGCdestination::ConnectTimeout.

Parameters:
Value Value to set ConnectTimeout to.

void IGCdestination::WaitForDisconnect (   ) 
 

Waits until the plugin is disconnected from Iguana.

May not be called from within an event handler (for example, may not be called from within the IGCdestination::OnDisconnected handler).

IGCboolean IGCdestination::WaitForDisconnectWithTimeout (  IGCint32  TimeoutInMilliseconds  ) 
 

Waits until either the plugin is disconnected from Iguana, or a specified timeout elapses.

May not be called from within an event handler (for example, may not be called from within the IGCdestination::OnDisconnected handler).

Parameters:
TimeoutInMilliseconds Timeout (in milliseconds) to wait for disconnection.
Returns:
Returns true if the plugin disconnected from Iguana, or false if the timeout elapsed before the plugin was disconnected from Iguana.

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