EMA C++ Edition
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
List of all members | Public Types
thomsonreuters::ema::access::OmmConsumer Class Reference

OmmConsumer class encapsulates functionality of an Omm consuming type application. More...

Public Types

enum  DispatchReturn {
  TimeoutEnum = -1,
  DispatchedEnum = 0
}
 
enum  DispatchTimeout {
  InfiniteWaitEnum = -1,
  NoWaitEnum = 0
}
 

Public Member Functions

Constructor
 OmmConsumer (const OmmConsumerConfig &config)
 
 OmmConsumer (const OmmConsumerConfig &config, OmmConsumerClient &client, void *closure=0)
 
 OmmConsumer (const OmmConsumerConfig &config, OmmConsumerErrorClient &client)
 
 OmmConsumer (const OmmConsumerConfig &config, OmmConsumerClient &adminClient, OmmConsumerErrorClient &errorClient, void *closure=0)
 
Destructor
virtual ~OmmConsumer ()
 
Accessors
const EmaStringgetConsumerName () const
 
Operations
UInt64 registerClient (const ReqMsg &reqMsg, OmmConsumerClient &client, void *closure=0, UInt64 parentHandle=0)
 
UInt64 registerClient (const TunnelStreamRequest &tunnelStreamRequest, OmmConsumerClient &client, void *closure=0)
 
void reissue (const ReqMsg &reqMsg, UInt64 handle)
 
void submit (const GenericMsg &genericMsg, UInt64 handle)
 
void submit (const PostMsg &postMsg, UInt64 handle)
 
Int64 dispatch (Int64 dispatchTimeout=NoWaitEnum)
 
void unregister (UInt64 handle)
 
void getChannelInformation (ChannelInformation &)
 
void getChannelStatistics (ChannelStatistics &)
 
void modifyIOCtl (Int32 code, Int32 value)
 

Detailed Description

OmmConsumer provides interfaces to open, modify and close items. It establishes and maintains connection to server, maintains open item watch list, performs connection and item recovery, etc.

OmmConsumer provides a default behaviour / functionality. This may be tuned / modified by application when using OmmConsumerConfig.

Application interacts with server through the OmmConsumer interface methods. The results of these interactions are communicated back to application through OmmConsumerClient and OmmConsumerErrorclient.

The following code snippet shows basic usage of OmmConsumer class in a simple consumer type app. This application opens a regular streaming item named RTR from a service RDF from the 1.1.1.1 server on port 14002.

// create an implementation for OmmConsumerClient to process received item messages
class AppClient : public OmmConsumerClient
{
void onRefreshMsg( const RefreshMsg& , const OmmConsumerEvent& );
void onUpdateMsg( const UpdateMsg& , const OmmConsumerEvent& );
void onStatusMsg( const StatusMsg& , const OmmConsumerEvent& );
};
AppClient appClient;
// instantiate OmmConsumer object and connect it to a server
OmmConsumer consumer( OmmConsumerConfig().host( "1.1.1.1:14002" ) );
// open an item of interest
consumer.registerClient( ReqMsg().name( "RTR" ).serviceName( "RDF" ) );

The following code snippet shows usage of OmmConsumer class to obtain data from the Auxiliary Services Gateway (or ASG). This application opens a tunnel stream to an ASG through the 1.1.1.1 server on port 14002. The tunnel stream is open from the ASG provided service named ASG_SERVICE. Then a streaming item named IBM_ASG is open on that stream from a service Id of 1.

// create an implementation for OmmConsumerClient to process received item messages.
// this object will process tunnel item and sub item messages
class AppClient : public OmmConsumerClient
{
void onRefreshMsg( const RefreshMsg& , const OmmConsumerEvent& );
void onUpdateMsg( const UpdateMsg& , const OmmConsumerEvent& );
void onStatusMsg( const StatusMsg& , const OmmConsumerEvent& );
};
AppClient appClient;
// instantiate OmmConsumer object and connect it to a server
OmmConsumer consumer( OmmConsumerConfig().host( "1.1.1.1:14002" ) );
// create and populate TunnelStreamRequest object
CosAuthentication cosAuthentication;
cosAuthentication.type( CosAuthentication::OmmLoginEnum );
CosDataIntegrity cosDataIntegrity;
cosDataIntegrity.type( CosDataIntegrity::ReliableEnum );
CosFlowControl cosFlowControl;
cosFlowControl.type( CosFlowControl::BidirectionalEnum )
.recvWindowSize( 1200 )
.sendWindowSize( 1200 );
CosGuarantee cosGuarantee;
cosGuarantee.type( CosGuarantee::NoneEnum );
ClassOfService cos;
cos.authentication( cosAuthentication )
.dataIntegrity( cosDataIntegrity )
.flowControl( cosFlowControl )
.guarantee( cosGuarantee );
TunnelStreamRequest tsr;
tsr.classOfService( cos )
.domainType( MMT_SYSTEM )
.name( "TUNNEL_STREAM" )
.serviceName( "ASG_SERVICE" )
.responseTimeout( 45 );
// open tunnel stream
UInt64 tunnelStreamHandle = consumer.registerClient( tsr, appClient );
// open sub item
UInt64 subItemHandle = consumer.registerClient(
ReqMsg().domainType( MMT_MARKET_PRICE ).name( "IBM_ASG" ).serviceId( 1 ),
client, (void*)1, tunnelStreamHandle );
See Also
OmmConsumerConfig, OmmConsumerClient, OmmConsumerErrorClient, OmmException, TunnelStreamRequest

Definition at line 137 of file OmmConsumer.h.

Member Enumeration Documentation

Enumerator
TimeoutEnum 

no message was dispatch on this dispatch call

DispatchedEnum 

a message was dispatched on this dispatch call

Definition at line 151 of file OmmConsumer.h.

Enumerator
InfiniteWaitEnum 

dispatch blocks till a message arrives

NoWaitEnum 

dispatch exits immediately even if there is no message

Definition at line 143 of file OmmConsumer.h.

Constructor & Destructor Documentation

thomsonreuters::ema::access::OmmConsumer::OmmConsumer ( const OmmConsumerConfig config)

Create an OmmConsumer with OmmConsumerConfig. The OmmConsumer enables functionality that includes subscribing, posting and distributing generic messages.

Remarks
Enables exception throwing as means of error reporting.
This affects exceptions thrown from OmmConsumer methods
thomsonreuters::ema::access::OmmConsumer::OmmConsumer ( const OmmConsumerConfig config,
OmmConsumerClient client,
void *  closure = 0 
)
Create an OmmConsumer with OmmConsumerConfig. The OmmConsumer enables functionality

that includes subscribing, posting and distributing generic messages. This constructor will also register for all login events via the provided OmmConsumerClient and optional closure.

Remarks
Enables exception throwing as means of error reporting.
This affects exceptions thrown from OmmConsumer methods
thomsonreuters::ema::access::OmmConsumer::OmmConsumer ( const OmmConsumerConfig config,
OmmConsumerErrorClient client 
)

Create an OmmConsumer with OmmConsumerConfig with an OmmConsumerErrorClient that provides select global errors via callbacks opposed to exception.The OmmConsumer enables functionality that includes subscribing, posting and distributing generic messages.

Remarks
Enables OmmConsumerErrorClient's callbacks as means of error reporting.
This affects OmmConsumer methods that would throw exceptions otherwise.
thomsonreuters::ema::access::OmmConsumer::OmmConsumer ( const OmmConsumerConfig config,
OmmConsumerClient adminClient,
OmmConsumerErrorClient errorClient,
void *  closure = 0 
)
Create an OmmConsumer with OmmConsumerConfig with an OmmConsumerErrorClient that provides

select global errors via callbacks opposed to exception.The OmmConsumer enables functionality that includes subscribing, posting and distributing generic messages. This constructor will also register for all login events via the provided OmmConsumerClient and optional closure.

Remarks
Enables OmmConsumerErrorClient's callbacks as means of error reporting.
This affects OmmConsumer methods that would throw exceptions otherwise.
virtual thomsonreuters::ema::access::OmmConsumer::~OmmConsumer ( )
virtual

Destructor.

Member Function Documentation

Int64 thomsonreuters::ema::access::OmmConsumer::dispatch ( Int64  dispatchTimeout = NoWaitEnum)

Relinquish application thread of control to receive callbacks via OmmConsumerClient descendant.

Remarks
Requires OperationalModel to be set to UserDispatchEnum.
Parameters
[in]dispatchTimeoutspecifies time in microseconds to wait in dispatch() for a message to dispatch (DispatchTimeout enumerations provide predefined values)
Returns
DispatchReturn::TimeoutEnum if nothing was dispatched; DispatchReturn::DispatchedEnum otherwise
Exceptions
OmmInvalidUsageExceptionif OperationalModel is not set to UserDispatchEnum
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmConsumer::getChannelInformation ( ChannelInformation )

Provides channel information about the active channel.

Parameters
[in]callerprovider ChannelInformation&; parameter will be cleared and then current channel information will be provided
Returns
void
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmConsumer::getChannelStatistics ( ChannelStatistics )
Provides channel statistics about the active channel.
Parameters
[in]callerprovider ChannelStatistics&; parameter will be cleared and then current channel statistics will be provided
Exceptions
OmmInvalidUsageExceptionif it cannot get the channel statistics
Returns
void
Remarks
This method is Object Level Thread Safe Method
const EmaString& thomsonreuters::ema::access::OmmConsumer::getConsumerName ( ) const

Retrieve internally generated consumer instance name.

Returns
name of this OmmConsumer instance
void thomsonreuters::ema::access::OmmConsumer::modifyIOCtl ( Int32  code,
Int32  value 
)

Allows modifying some I/O values programmatically for a channel to override the default values.

Parameters
[in]codeprovides Code of I/O option defined in IOCtlCode::IOCtlCodeEnum to modify.
[in]valueprovides Value to modify I/O option to
Returns
void
Exceptions
OmmInvalidUsageExceptionif failed to modify I/O option to
Remarks
This method is Object Level Thread Safe Method
UInt64 thomsonreuters::ema::access::OmmConsumer::registerClient ( const ReqMsg reqMsg,
OmmConsumerClient client,
void *  closure = 0,
UInt64  parentHandle = 0 
)

Opens an item stream

Parameters
[in]reqMsgspecifies item and its unique attributes
[in]clientspecifies OmmConsumerClient instance receiving notifications about this item
[in]closurespecifies application defined item identification
[in]parentHandlespecifies handle of tunnel stream over which this substream is open (required for substreams)
Returns
item identifier (a.k.a. handle)
Exceptions
OmmMemoryExhaustionExceptionif system runs out of memory
OmmInvalidUsageExceptionif application passes invalid ReqMsg
OmmInvalidHandlExceptionif application passes invalid parent item handle
Remarks
This method is Object Level Thread Safe Method
if OmmConsumerErrorClient is used and an error condition is encountered, then null handle is returned
UInt64 thomsonreuters::ema::access::OmmConsumer::registerClient ( const TunnelStreamRequest tunnelStreamRequest,
OmmConsumerClient client,
void *  closure = 0 
)

Opens a tunnel stream

Parameters
[in]tunnelStreamRequestspecifies tunnel stream attributes
[in]clientspecifies OmmConsumerClient instance receiving notifications about this item
[in]closurespecifies application defined item identification
Returns
tunnel stream handle (a.k.a. parentHandle)
Exceptions
OmmMemoryExhaustionExceptionif system runs out of memory
OmmInvalidUsageExceptionif application passes invalid TunnelStreamRequest
Remarks
This method is Object Level Thread Safe Method
if OmmConsumerErrorClient is used and an error condition is encountered, then null handle is returned
void thomsonreuters::ema::access::OmmConsumer::reissue ( const ReqMsg reqMsg,
UInt64  handle 
)

Changes the interest in an open item stream. The first formal parameter houses a ReqMsg. ReqMsg attributes that may change are Priority(), InitialImage(), InterestAfterRefresh(), Pause() and Payload ViewData(). The second formal parameter is a handle that identifies the open stream to be modified.

Parameters
[in]reqMsgspecifies modifications to the open item stream
[in]handleidentifies item to be modified
Returns
void
Exceptions
OmmInvalidHandleExceptionif passed in handle does not refer to an open stream
OmmInvalidUsageExceptionif passed in ReqMsg violates reissue rules
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmConsumer::submit ( const GenericMsg genericMsg,
UInt64  handle 
)

Sends a GenericMsg.

Parameters
[in]genericMsgspecifies GenericMsg to be sent on the open item stream
[in]identifiesitem stream on which to send the GenericMsg
Returns
void
Exceptions
OmmInvalidHandleExceptionif passed in handle does not refer to an open stream
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmConsumer::submit ( const PostMsg postMsg,
UInt64  handle 
)

Sends a PostMsg. Accepts a PostMsg and optionally a handle associated to an open item stream. Specifying an item handle is known as "on stream posting". Specifying a login handle is known as "off stream posting".

Parameters
[in]postMsgspecifies PostMsg to be sent on the open item stream
[in]identifiesitem stream on which to send the PostMsg
Returns
void
Exceptions
OmmInvalidHandleExceptionif passed in handle does not refer to an open stream
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmConsumer::unregister ( UInt64  handle)

Relinquishes interest in an open item stream.

Parameters
[in]handleidentifies item to close
Returns
void
Remarks
This method is Object Level Thread Safe Method