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

OmmProvider class encapsulates functionality of an Interactive and NonInteractive OmmProvider application. More...

Public Types

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

Public Member Functions

Constructor
 OmmProvider (const OmmProviderConfig &config)
 
 OmmProvider (const OmmProviderConfig &config, OmmProviderClient &client, void *closure=0)
 
 OmmProvider (const OmmProviderConfig &config, OmmProviderErrorClient &errorclient)
 
 OmmProvider (const OmmProviderConfig &config, OmmProviderClient &client, OmmProviderErrorClient &errorclient, void *closure=0)
 
Destructor
virtual ~OmmProvider ()
 
Accessors
const EmaStringgetProviderName () const
 
OmmProviderConfig::ProviderRole getProviderRole () const
 
Operations
UInt64 registerClient (const ReqMsg &reqMsg, OmmProviderClient &client, void *closure=0)
 
void reissue (const ReqMsg &reqMsg, UInt64 handle)
 
void submit (const GenericMsg &genericMsg, UInt64 handle)
 
void submit (const RefreshMsg &refreshMsg, UInt64 handle)
 
void submit (const UpdateMsg &updateMsg, UInt64 handle)
 
void submit (const StatusMsg &statusMsg, UInt64 handle)
 
Int64 dispatch (Int64 timeOut=NoWaitEnum)
 
void unregister (UInt64 handle)
 
void submit (const AckMsg &ackMsg, UInt64 handle)
 
void getConnectedClientChannelInfo (EmaVector< ChannelInformation > &)
 
void getConnectedClientChannelStats (UInt64 clientHandle, ChannelStatistics &cs)
 
void getChannelInformation (ChannelInformation &)
 
void modifyIOCtl (Int32 code, Int32 value, UInt64 handle=0)
 
void closeChannel (UInt64 clientHandle)
 

Detailed Description

OmmProvider class provides interfaces for interactive and non interactive OmmProvider application use cases. The specific use case is determined through the usage of the respective OmmProvider class constructor.

The non interactive use case allows applications to publish items without any item request. In this case OmmProvider establishes and maintains the configured connection to ADH. Right after the connection is established, the application may start publishing item specific data while the app assigns unique handles or identifiers to each item.

The interactive use case works based on the item requests received from client applications. In this case OmmProvider establishes a server port to which clients connect. After clients login request is accepted, the provider application may receive item requests from the connected client application. The requested items are identified by the EMA with a unique handle or identifier. Provider application uses this handle to respond to the item requests.

OmmProvider provides a default behaviour / functionality. This may be tuned / modified by application when using OmmNiProviderConfig or OmmIProviderConfig.

Application interacts with ADH or clients through the OmmProvider interface methods. The results of these interactions are communicated back to application through OmmProviderClient and OmmProviderErrorClient.

The following code snippet shows basic usage of OmmProvider class in a simple non-interactive provider application.

// create an implementation for OmmProviderClient to process received Login and Dictionary messages
class AppClient : public OmmProviderClient
{
void onRefreshMsg( const RefreshMsg& , const OmmProviderEvent& );
void onStatusMsg( const StatusMsg& , const OmmProviderEvent& );
};
AppClient appClient;
// instantiate OmmProvider object and connect it to a host
OmmProvider provider( OmmNiProviderConfig().host( "..." ).user( "..." ) );
UInt64 itemHandle = 5;
provider.submit( RefreshMsg().serviceName( "NI_PUB" ).name( "IBM.N" )
.state( OmmState::OpenEnum, OmmState::OkEnum, OmmState::NoneEnum, "UnSolicited Refresh Completed" )
.payload( FieldList()
.addReal( 22, 3990, OmmReal::ExponentNeg2Enum )
.addReal( 25, 3994, OmmReal::ExponentNeg2Enum )
.addReal( 30, 9, OmmReal::Exponent0Enum )
.addReal( 31, 19, OmmReal::Exponent0Enum )
.complete() )
.complete(), itemHandle );

The following code snippet shows basic usage of OmmProvider class in a simple interactive provider application.

// create an implementation for OmmProviderClient to process request messages for login and market price domains
void AppClient::onReqMsg( const ReqMsg& reqMsg, const OmmProviderEvent& event )
{
switch ( reqMsg.getDomainType() )
{
case MMT_LOGIN:
processLoginRequest( reqMsg, event );
break;
processMarketPriceRequest( reqMsg, event );
break;
}
}
void AppClient::processLoginRequest( const ReqMsg& reqMsg, const OmmProviderEvent& event )
{
event.getProvider().submit(RefreshMsg().domainType(MMT_LOGIN).name(reqMsg.getName()).nameType(USER_NAME).complete().
attrib( ElementList().complete() ).solicited( true ).
event.getHandle() );
}
void AppClient::processMarketPriceRequest( const ReqMsg& reqMsg, const OmmProviderEvent& event )
{
event.getProvider().submit( RefreshMsg().name( reqMsg.getName() ).serviceName( reqMsg.getServiceName() ).
solicited( true ).state( OmmState::OpenEnum, OmmState::OkEnum, OmmState::NoneEnum, "Refresh Completed" ).
payload( FieldList().
addReal( 22, 3990, OmmReal::ExponentNeg2Enum ).
addReal( 25, 3994, OmmReal::ExponentNeg2Enum ).
addReal( 30, 9, OmmReal::Exponent0Enum ).
addReal( 31, 19, OmmReal::Exponent0Enum ).
complete() ).
complete(), event.getHandle() );
itemHandle = event.getHandle();
}
AppClient appClient;
// instantiate OmmProvider object and bind a server port on 14002
OmmProvider provider( OmmIProviderConfig().port( "14002" ), appClient );
while ( itemHandle == 0 ) sleep(1000);
for ( Int32 i = 0; i < 60; i++ )
{
provider.submit( UpdateMsg().payload( FieldList().
addReal( 22, 3391 + i, OmmReal::ExponentNeg2Enum ).
addReal( 30, 10 + i, OmmReal::Exponent0Enum ).
complete() ), itemHandle );
sleep( 1000 );
}
See Also
OmmProviderConfig, OmmIProviderConfig, OmmNiProviderConfig, OmmProviderClient, OmmProviderErrorClient, OmmException

Definition at line 161 of file OmmProvider.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 175 of file OmmProvider.h.

Enumerator
InfiniteWaitEnum 

dispatch blocks till a message arrives

NoWaitEnum 

dispatch exits immediately even if there is no message

Definition at line 167 of file OmmProvider.h.

Constructor & Destructor Documentation

thomsonreuters::ema::access::OmmProvider::OmmProvider ( const OmmProviderConfig config)

Create an OmmProvider with OmmNiProviderConfig. The OmmProvider enables functionality that includes non interactive distribution of item refresh, update, status and generic messages.

Parameters
[in]configspecifies instance of OmmNiProviderConfig
Remarks
Enables exception throwing as means of error reporting.
This affects exceptions thrown from OmmProvider methods
thomsonreuters::ema::access::OmmProvider::OmmProvider ( const OmmProviderConfig config,
OmmProviderClient client,
void *  closure = 0 
)
Create an OmmProvider with OmmIProviderConfig. The OmmProvider enables functionality

that includes interactive distribution of item refresh, update, status, generic and ack messages.

Parameters
[in]configspecifies instance of OmmIProviderConfig
[in]clientspecifies instance of OmmProviderClient
[in]closurespecifies application defined identification
Remarks
Enables exception throwing as means of error reporting.
This affects exceptions thrown from OmmProvider methods
thomsonreuters::ema::access::OmmProvider::OmmProvider ( const OmmProviderConfig config,
OmmProviderErrorClient errorclient 
)

Create an OmmProvider with OmmNiProviderConfig with an OmmProviderErrorClient that provides select global errors via callbacks instead of via exceptions.The OmmProvider enables functionality that includes non interactive distribution of item refresh, update, status and generic messages.

Parameters
[in]configspecifies instance of OmmNiProviderConfig
[in]errorClientspecifies instance of OmmProviderErrorClient
Remarks
Enables OmmProviderErrorClient's callbacks as means of error reporting.
This affects OmmProvider methods that would throw exceptions otherwise.
thomsonreuters::ema::access::OmmProvider::OmmProvider ( const OmmProviderConfig config,
OmmProviderClient client,
OmmProviderErrorClient errorclient,
void *  closure = 0 
)
Create an OmmProvider with OmmIProviderConfig with an OmmProviderErrorClient that provides

select global errors via callbacks instead of via exceptions.The OmmProvider enables functionality that includes interactive distribution of item refresh, update, status, generic and ack messages.

Parameters
[in]configspecifies instance of OmmIProviderConfig
[in]clientspecifies instance of OmmProviderClient
[in]errorClientspecifies instance of OmmProviderErrorClient
[in]closurespecifies application defined identification
Remarks
Enables OmmProviderErrorClient's callbacks as means of error reporting.
This affects OmmProvider methods that would throw exceptions otherwise.
virtual thomsonreuters::ema::access::OmmProvider::~OmmProvider ( )
virtual

Destructor.

Member Function Documentation

void thomsonreuters::ema::access::OmmProvider::closeChannel ( UInt64  clientHandle)

Closes channel for connected client's channel and associated items. Only relevant to IProvider applications. This method throws an exception is called by NiProvider applications.

Parameters
[in]clientHandlespecifies a client handle to close its channel.
Returns
void
Exceptions
OmmInvalidUsageExceptionif is called by an NiProvider application or an invalid client handle.
Remarks
This method is Object Level Thread Safe Method
Int64 thomsonreuters::ema::access::OmmProvider::dispatch ( Int64  timeOut = NoWaitEnum)

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

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

Provides channel information about the active channel. Only relevant to NiProvider application. This method throws an exception is called by IProvider applications.

Parameters
[in]callerprovider ChannelInformation&; parameter will be cleared and then current channel information will be provided
Returns
void
Exceptions
OmmInvalidUsageExceptionif is called by an IProvider applications.
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmProvider::getConnectedClientChannelInfo ( EmaVector< ChannelInformation > &  )

Provides channel information about connected clients. Only relevant to IProvider applications. This method throws an exception is called by NiProvider applications.

Parameters
[in]callerprovided EmaVector<ChannelInformation>; vector will be cleared before channel information about connected clients is added
Returns
void
Exceptions
OmmInvalidUsageExceptionif is called by an NiProvider application.
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmProvider::getConnectedClientChannelStats ( UInt64  clientHandle,
ChannelStatistics cs 
)

Provides channel statistical information about connected client. Only relevant to IProvider applications. This method throws an exception is called by NiProvider applications.

Parameters
[in]clientHandleidentifieshandle associated with connected client information about connected clients is added
[out]cscaller provided ChannelStatistics; data will be cleared before statistics information about connected clients is added
Returns
void
Exceptions
OmmInvalidUsageExceptionif is called by an NiProvider application.
Remarks
This method is Object Level Thread Safe Method
const EmaString& thomsonreuters::ema::access::OmmProvider::getProviderName ( ) const

Retrieve internally generated OmmProvider instance name.

Returns
name of this OmmProvider instance
OmmProviderConfig::ProviderRole thomsonreuters::ema::access::OmmProvider::getProviderRole ( ) const

Retrieve Provider's role

Returns
role of this OmmProvider instance
void thomsonreuters::ema::access::OmmProvider::modifyIOCtl ( Int32  code,
Int32  value,
UInt64  handle = 0 
)

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
[in]identifieshandle associated with an item or login stream. This parameter is needed or IProvider applications only.
Returns
void
Exceptions
OmmInvalidUsageExceptionif fails to modify I/O option to
Remarks
This method is Object Level Thread Safe Method
UInt64 thomsonreuters::ema::access::OmmProvider::registerClient ( const ReqMsg reqMsg,
OmmProviderClient client,
void *  closure = 0 
)

Opens an item stream (i.e. login stream and dictionary stream)

Parameters
[in]reqMsgspecifies item and its unique attributes
[in]clientspecifies OmmProviderClient instance receiving notifications about this item
[in]closurespecifies application defined item identification
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 OmmProviderErrorClient is used and an error condition is encountered, then null handle is returned
void thomsonreuters::ema::access::OmmProvider::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::OmmProvider::submit ( const GenericMsg genericMsg,
UInt64  handle 
)

Sends a GenericMsg.

Parameters
[in]genericMsgspecifies GenericMsg to be sent on the open item stream
[in]identifieshandle associated with an item stream on which to send the GenericMsg
Returns
void
Exceptions
OmmInvalidUsageExceptionif failed to submit genericMsg
OmmInvalidHandleExceptionif passed in handle does not refer to an open stream
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmProvider::submit ( const RefreshMsg refreshMsg,
UInt64  handle 
)

Sends a RefreshMsg.

Parameters
[in]refreshMsgspecifies RefreshMsg to be sent
[in]identifieshandle associated with an item stream on which to send the RefreshMsg
Returns
void
Exceptions
OmmInvalidUsageExceptionif failed to submit refreshMsg
OmmInvalidHandleExceptionif passed in handle does not refer to an open stream
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmProvider::submit ( const UpdateMsg updateMsg,
UInt64  handle 
)

Sends a UpdateMsg.

Parameters
[in]updateMsgspecifies UpdateMsg to be sent
[in]identifieshandle associated with an item stream on which to send the UpdateMsg
Returns
void
Exceptions
OmmInvalidUsageExceptionif failed to submit updateMsg
OmmInvalidHandleExceptionif passed in handle does not refer to an open stream
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmProvider::submit ( const StatusMsg statusMsg,
UInt64  handle 
)

Sends a StatusMsg.

Parameters
[in]statusMsgspecifies StatusMsg to be sent
[in]identifieshandle associated with an item stream on which to send the StatusMsg
Returns
void
Exceptions
OmmInvalidUsageExceptionif failed to submit statusMsg
OmmInvalidHandleExceptionif passed in handle does not refer to an open stream
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmProvider::submit ( const AckMsg ackMsg,
UInt64  handle 
)

Sends an AckMsg.

Parameters
[in]ackMsgspecifies AckMsg to be sent on the open item stream
[in]identifieshandle associated with an item stream on which to send the AckMsg
Returns
void
Exceptions
OmmInvalidUsageExceptionif failed to submit ackMsg
OmmInvalidHandleExceptionif passed in handle does not refer to an open stream
Remarks
This method is Object Level Thread Safe Method
void thomsonreuters::ema::access::OmmProvider::unregister ( UInt64  handle)

Relinquishes interest in an open item stream if item handle is passed in. Closes server port if listener handle is passed in.

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