Files

652 lines
22 KiB
C++

/**
* @file include/ActivOneApi/Session.h
*
* @brief Header for the Session class.
*/
#if (!defined ACTIV_ONE_API_SESSION_H)
#define ACTIV_ONE_API_SESSION_H
#include "ActivOneApi/External.h"
#include "ActivOneApi/TypeDefinitions.h"
#include "ActivOneApi/Constants/EventTypes.h"
#include "ActivOneApi/Constants/PublishFlags.h"
#include "ActivOneApi/Constants/SessionStates.h"
#include "ActivOneApi/Detail/SessionImplFwd.h"
#include "ActivMiddleware/ActivBase/FieldTypes/FieldMap.h"
#include "ActivMiddleware/CxxYZ/memory.h"
//! Activ namespace.
namespace Activ
{
class ManagedEndPoint;
//! OneApi namespace.
namespace OneApi
{
class FieldListBuilder;
class ISessionHandler;
class ISnapshotHandler;
class IStreamHandler;
class ISubscriptionHandler;
class ITopicQueryHandler;
class Metadata;
template <typename T> class SessionImplBase;
class StandardSessionImpl;
class StreamMessage;
class Topic;
class TopicId;
class TopicQuerySymbolPattern;
// ---------------------------------------------------------------------------------------------------------------------------------
//! Session class.
class Session : public Boost::noncopyable
{
public:
/**
* @brief Construct from parameters.
*
* See Appendix 1 of the ActivOneApi documentation for parameter details.
*
* @param parameters a FieldMap containing Session configuration parameters.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API explicit Session(const FieldMap &parameters = FieldMap());
/**
* @brief Construct from parameters.
*
* See Appendix 1 of the ActivOneApi documentation for parameter details.
*
* @param parameters a FieldMap containing Session configuration parameters.
* @param sessionHandler ISessionHandler providing Session callbacks for connect, disconnect, logging.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Session(const FieldMap &parameters, ISessionHandler &sessionHandler);
/**
* @brief Construct with an external ManagedEndPoint.
* @private
*
* See Appendix 1 of the ActivOneApi documentation for parameter details.
*
* @param managedEndPoint
* @param parameters a FieldMap containing Session configuration parameters.
* @param sessionHandler ISessionHandler providing Session callbacks for connect, disconnect, logging.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Session(ManagedEndPoint &managedEndPoint, const FieldMap &parameters, ISessionHandler &sessionHandler);
//! Destructor.
ACTIV_ONE_API ~Session();
#if (!defined ACTIV_LITE_FRAMEWORK)
//! Implicit conversion to ManagedEndPoint.
ACTIV_ONE_API operator ManagedEndPoint&();
#endif
/**
* @brief Initiate a synchronous connection to the ActivOneApiDaemon.
*
* See Appendix 1 of the ActivOneApi documentation for parameter details.
*
* @param connectParameters a FieldMap containing parameters to use for the connection.
* @param timeout period in milliseconds before the connection attempt is aborted.
*
* @throw Exception
*/
ACTIV_ONE_API void Connect(const FieldMap &connectParameters, const uint32_t timeout = 30000);
/**
* @brief Initiate an asynchronous connection to the ActivOneApiDaemon.
*
* See Appendix 1 of the ActivOneApi documentation for parameter details.
*
* @param connectParameters a FieldMap containing parameters to use for the connection.
*
* @throw Exception
*/
ACTIV_ONE_API void AsyncConnect(const FieldMap &connectParameters);
/**
* @brief Disconnect from the ActivOneApiDaemon.
*
* @throw Exception
*/
ACTIV_ONE_API void Disconnect();
/**
* @brief Process the Session.
*
* @param canBlock when true this method will block for short periods waiting for events.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_EXIT returned when Shutdown() has been called.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API StatusCode Process(const bool canBlock = true);
/**
* @brief Run the Session.
*
* This thread will run the Session until Shutdown() is called.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API void Run();
/**
* @brief Shutdown the Session.
*
* This method is thread safe.
*
* @param session the Session to initiate a shutdown for.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API static void Shutdown(Session &session);
/**
* @brief Get a notification handle (POSIX only).
*
* @param handle a HANDLE suitable for use with select, poll etc.
*
* @throw Exception
*/
ACTIV_ONE_API void GetNotificationHandle(HANDLE &handle) const;
/**
* @brief Flush any outstanding requests to the ActivOneApiDaemon (if connected).
*
* The API will automatically flush requests in a timely fashion. However, to achieve the best snapshot latency the user can
* Flush() immediately after issuing requests.
*
* This call only affects direct Snapshot() requests.
*/
ACTIV_ONE_API void Flush();
/**
* @brief Get the current SessionState.
*
* @return The current SessionState.
*/
ACTIV_ONE_API SessionState GetState() const;
/**
* @brief Get metadata.
*
* Basic data source, dictionary and symbology information will only be available when connecting to R9 gateways.
*
* By default the API does not download dictionary field data. This can be controlled with the FID_ENABLE_DICTIONARY_DOWNLOAD
* and FID_DICTIONARY_DOWNLOAD_LIST session parameters. See the documentation for further details.
*
* @return A reference the stored MetaData if available.
*/
ACTIV_ONE_API const Metadata &GetMetadata() const;
/**
* @brief Post user message.
*
* This method is thread safe.
* Allows posting a message from any thread to the thread processing the Session.
*
* @param session the Session to post a message to.
* @param pMessage a pointer the message to be sent.
* @param messageLength the length of the buffer pointed to by @a pMessage.
*
* @throw Exception
*/
ACTIV_ONE_API static void PostUserMessage(Session &session, const void *pMessage, const size_t messageLength);
/**
* @brief Get parameters.
*
* @return The current Session parameters
*/
ACTIV_ONE_API const FieldMap &GetParameters() const;
/**
* @brief Get default Session parameters.
*
* @return The default Session parameters
*/
ACTIV_ONE_API static FieldMap GetDefaultParameters();
/**
* @brief Register snapshot parameters.
*
* See Appendix 2 of the ActivOneApi documentation for parameter details.
*
* @param snapshotParameters a FieldMap containing snapshot parameters.
*
* @return The Handle for these parameters.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle RegisterSnapshotParameters(const FieldMap &snapshotParameters);
/**
* @brief Request a snapshot.
*
* SymbologyId is assumed to be SYMBOLOGY_NATIVE.
*
* @param dataSourceId the data source to use to fulfill the request.
* @param symbol the symbol to request.
* @param snapshotHandler the ISnapshotHandler processing callbacks.
* @param snapshotParameters optional snapshot parameters Handle to use with this request (see RegisterSnapshotParameters()).
* @param pUserData optional pointer to user data to be associated with this request and provided during callbacks in Context.
*
* @return The Handle for this request.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle Snapshot(const DataSourceId dataSourceId, const String &symbol, ISnapshotHandler &snapshotHandler,
const Handle snapshotParameters = HANDLE_UNDEFINED, void *pUserData = ACTIV_NULLPTR);
/**
* @brief Request a snapshot.
*
* @param dataSourceId the data source to use to fulfill the request.
* @param symbologyId the SymbologyId used to define @a symbol.
* @param symbol the symbol to request.
* @param snapshotHandler the ISnapshotHandler processing callbacks.
* @param snapshotParameters optional snapshot parameters Handle to use with this request (see RegisterSnapshotParameters()).
* @param pUserData optional pointer to user data to be associated with this request and provided during callbacks in Context.
*
* @return The Handle for this request.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle Snapshot(const DataSourceId dataSourceId, const SymbologyId symbologyId, const String &symbol,
ISnapshotHandler &snapshotHandler, const Handle snapshotParameters = HANDLE_UNDEFINED, void *pUserData = ACTIV_NULLPTR);
/**
* @brief Request a snapshot.
*
* SymbologyId is assumed to be SYMBOLOGY_NATIVE.
*
* @param topicId the TopicId to request.
* @param snapshotHandler the ISnapshotHandler processing callbacks.
* @param snapshotParameters optional snapshot parameters Handle to use with this request (see RegisterSnapshotParameters()).
* @param pUserData optional pointer to user data to be associated with this request and provided during callbacks in Context.
*
* @return The Handle for this request.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle Snapshot(const TopicId &topicId, ISnapshotHandler &snapshotHandler,
const Handle snapshotParameters = HANDLE_UNDEFINED, void *pUserData = ACTIV_NULLPTR);
/**
* @brief Register subscription parameters.
*
* See Appendix 3 of the ActivOneApi documentation for parameter details.
*
* @param subscriptionParameters a FieldMap containing subscription parameters.
*
* @return The Handle for these parameters.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle RegisterSubscriptionParameters(const FieldMap &subscriptionParameters);
/**
* @brief Request a subscription.
*
* SymbologyId is assumed to be SYMBOLOGY_NATIVE.
*
* @param dataSourceId the data source to use to fulfill the request.
* @param symbol the symbol to request.
* @param subscriptionHandler the ISubscriptionHandler processing callbacks.
* @param subscriptionParameters optional subscription parameters Handle to use with this request
* (see RegisterSubscriptionParameters()).
* @param pUserData optional pointer to user data to be associated with this request and provided during callbacks in Context.
*
* @return The Handle for this request.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle Subscribe(const DataSourceId dataSourceId, const String &symbol, ISubscriptionHandler &subscriptionHandler,
const Handle subscriptionParameters = HANDLE_UNDEFINED, void *pUserData = ACTIV_NULLPTR);
/**
* @brief Request a subscription.
*
* @param dataSourceId the data source to use to fulfill the request.
* @param symbologyId the SymbologyId used to defined @a symbol.
* @param symbol the symbol to request.
* @param subscriptionHandler the ISubscriptionHandler processing callbacks.
* @param subscriptionParameters optional subscription parameters Handle to use with this request
* (see RegisterSubscriptionParameters()).
* @param pUserData optional pointer to user data to be associated with this request and provided during callbacks in Context.
*
* @return The Handle for this request.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle Subscribe(const DataSourceId dataSourceId, const SymbologyId symbologyId, const String &symbol,
ISubscriptionHandler &subscriptionHandler, const Handle subscriptionParameters = HANDLE_UNDEFINED,
void *pUserData = ACTIV_NULLPTR);
/**
* @brief Request a subscription.
*
* SymbologyId is assumed to be SYMBOLOGY_NATIVE.
*
* @param topicId the TopicId to request.
* @param subscriptionHandler the ISubscriptionHandler processing callbacks.
* @param subscriptionParameters optional subscription parameters Handle to use with this request
* (see RegisterSubscriptionParameters()).
* @param pUserData optional pointer to user data to be associated with this request and provided during callbacks in Context.
*
* @return The Handle for this request.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle Subscribe(const TopicId &topicId, ISubscriptionHandler &subscriptionHandler,
const Handle subscriptionParameters = HANDLE_UNDEFINED, void *pUserData = ACTIV_NULLPTR);
/**
* @brief Request a bulk subscription.
*
* This method provides a means to create a bulk content subscription. Bulk subscriptions have the following features:
*
* - No refresh is initiated, only background refresh is received.
* - Passive subscriptions only, no content is enabled for on demand feeds.
* - The APId being connected to must be configured to use a fixed side (no failover support).
* - No gap detection.
* - No TCP ingress support.
* - Only DATA_SOURCE_ACTIV, DATA_SOURCE_ACTIV_DELAYED, DATA_SOURCE_ACTIV_LOW_LATENCY and
* DATA_SOURCE_ACTIV_FEED_HANDLER are supported.
*
* @param dataSourceId the data source to use to fulfill the request.
* @param permissionId the permission id to subscribe to.
* @param partition the specific content partition to subscribe to.
* @param partitionCount the number of partitions to segment the data into.
* @param subscriptionHandler the ISubscriptionHandler processing callbacks.
* @param subscriptionParameters optional subscription parameters Handle to use with this request
* (see RegisterSubscriptionParameters()).
* @param pUserData optional pointer to user data to be associated with this request and provided during callbacks in Context.
*
* @return The Handle for this request.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle Subscribe(const DataSourceId dataSourceId, const PermissionId permissionId, const uint8_t partition,
const uint8_t partitionCount, ISubscriptionHandler &subscriptionHandler,
const Handle subscriptionParameters = HANDLE_UNDEFINED, void *pUserData = ACTIV_NULLPTR);
/**
* @brief Create an asynchronous symbol pattern topic query.
*
* @deprecated This method will be removed in the R9 API release.
*
* @param parameters a TopicQuerySymbolPattern containing details of the query.
* @param topicQueryHandler the ITopicQueryHandler processing callbacks.
* @param pUserData optional pointer to user data to be associated with this request and provided during callbacks in Context.
*
* @return The Handle for this request.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle Query(const TopicQuerySymbolPattern &parameters, ITopicQueryHandler &topicQueryHandler,
void *pUserData = ACTIV_NULLPTR);
/**
* @brief Create an asynchronous tag topic query.
*
* @param dataSourceId the data source for this query.
* @param tagExpression a String tag expression.
* @param topicQueryHandler the ITopicQueryHandler processing callbacks.
* @param pUserData optional pointer to user data to be associated with this request and provided during callbacks in Context.
*
* @return The Handle for this request.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle Query(const DataSourceId dataSourceId, const String &tagExpression, ITopicQueryHandler &topicQueryHandler,
void *pUserData = ACTIV_NULLPTR);
/**
* @brief Create a synchronous symbol pattern topic query.
*
* @deprecated This method will be removed in the R9 API release.
*
* @param parameters a TopicQuerySymbolPattern containing details of the query.
* @param queryResults reference to QueryResults object to receive the results of the topic query.
* @param timeout period in milliseconds before the query is aborted.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API void Query(const TopicQuerySymbolPattern &parameters, QueryResults &queryResults,
const uint32_t timeout = ACTIV_WAIT_INFINITE);
/**
* @brief Create a synchronous tag topic query.
*
* @param dataSourceId the data source for this query.
* @param tagExpression the query tag expression.
* @param queryResults reference to QueryResults object to receive the results of the topic query.
* @param timeout period in milliseconds before the query is aborted.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API void Query(const DataSourceId dataSourceId, const String &tagExpression, QueryResults &queryResults,
const uint32_t timeout = ACTIV_WAIT_INFINITE);
/**
* @brief Publish an update to a cache on the platform.
*
* The session must have been configured with push mode publishing to use this method.
*
* @param symbol the symbol the update is for.
* @param fieldListBuilder the FieldListBuilder containing the field data.
* @param tableNumber the table number to update must match the schema of the cache where applicable.
* @param permissionId the permission id to use, PERMISSION_ID_NONE allows access to all users.
* @param eventType the type of event.
* @param flags optional flags.
*
* @throw Exception
*/
ACTIV_ONE_API void Publish(const String &symbol, const FieldListBuilder &fieldListBuilder,
const TableNo tableNumber = TABLE_NO_UNDEFINED, const PermissionId permissionId = PERMISSION_ID_NONE,
const EventType eventType = EVENT_TYPE_NONE, const PublishFlag flags = PUBLISH_FLAG_NONE);
/**
* @brief Register a service.
*
* @param parameters the parameters of the service to register.
* @param streamHandler handler interface to receive open service requests.
* @param pUserData optional pointer to user data to be associated with the service and provided during callbacks in Context.
*
* @return Handle to the service.
*/
ACTIV_ONE_API Handle RegisterService(const FieldMap &parameters, IStreamHandler &streamHandler,
void *pUserData = ACTIV_NULLPTR);
/**
* @brief Get service parameters.
*
* @param serviceHandle the service handle.
*
* @return A reference to a FieldMap containing the service parameters for @a serviceHandle.
*
* @throw StatusCodeException
*/
ACTIV_ONE_API const FieldMap &GetServiceParameters(const Handle serviceHandle);
/**
* @brief Set the status of a service.
*
* Services are started with SERVICE_STATUS_OFFLINE.
*
* Services that are offline are not available to other users of the platform. This excludes directly connected clients.
*
* @param handle handle of the service to set the status for.
* @param serviceStatus the service status.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API void SetServiceStatus(const Handle handle, const ServiceStatus serviceStatus);
/**
* @brief Open stream on a service.
*
* @param serviceParameters the parameters of the service to connect to.
* @param fieldListBuilder FieldListBuilder containing the request data.
* @param streamHandler handler interface to receive the new stream callbacks.
* @param pUserData optional pointer to user data to be associated with the stream and provided during callbacks in Context.
*
* @return Handle to the stream.
*/
ACTIV_ONE_API Handle OpenService(const FieldMap &serviceParameters, const FieldListBuilder &fieldListBuilder,
IStreamHandler &streamHandler, void *pUserData = ACTIV_NULLPTR);
/**
* @brief Post a request on a stream.
*
* @param handle the handle of the stream to post the request on.
* @param messageType the message type of the request.
* @param fieldListBuilder FieldListBuilder containing the request data.
* @param streamHandler handler interface to receive the new stream's callbacks.
* @param pUserData optional pointer to user data to be associated with the stream and provided during callbacks in Context.
*
* @return Handle to the new stream.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle PostRequest(const Handle handle, const MessageType messageType,
const FieldListBuilder &fieldListBuilder, IStreamHandler &streamHandler, void *pUserData = ACTIV_NULLPTR);
/**
* @brief Post a non-streaming response to a request.
*
* If requestMessage.IsValidRequest() returns false then this method will throw an exception.
*
* @param requestMessage the request message to respond to.
* @param fieldListBuilder FieldListBuilder containing the response data.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API void PostResponse(StreamMessage &requestMessage, const FieldListBuilder &fieldListBuilder);
/**
* @brief Post a streaming response to a request.
*
* If requestMessage.IsValidRequest() returns false then this method will throw an exception.
*
* @param requestMessage the request message to respond to.
* @param fieldListBuilder FieldListBuilder containing the response data.
* @param streamHandler handler interface to receive the new stream's callbacks.
* @param pUserData optional pointer to user data to be associated with the stream and provided during callbacks in Context.
*
* @return Handle to the new stream.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API Handle PostStreamingResponse(StreamMessage &requestMessage, const FieldListBuilder &fieldListBuilder,
IStreamHandler &streamHandler, void *pUserData = ACTIV_NULLPTR);
/**
* @brief Post a message on a stream.
*
* @param handle the handle of the stream to post the message on.
* @param messageType the message type.
* @param fieldListBuilder FieldListBuilder containing the message data.
*/
ACTIV_ONE_API void PostMessage(const Handle handle, const MessageType messageType, const FieldListBuilder &fieldListBuilder);
/**
* @brief Reject a request.
*
* If requestMessage.IsValidRequest() returns false then this method will throw an exception.
*
* @param requestMessage the request message to reject.
* @param fieldListBuilder FieldListBuilder containing error response data.
*/
ACTIV_ONE_API void RejectRequest(StreamMessage &requestMessage, const FieldListBuilder &fieldListBuilder);
/**
* @brief Get Handle for the directory service stream.
*
* @return The directory service stream handle.
*
* @throw Exception
*/
ACTIV_ONE_API Handle GetDirectoryService() const;
/**
* @brief Close a free Handle (a Handle that is not being managed by a ScopedHandle).
*
* @param handle the Handle to close.
*
* @throw Exception
* @throw std::exception
*/
ACTIV_ONE_API void CloseHandle(const Handle handle);
/**
* @brief Is valid Handle.
*
* @param handle is the provided Handle valid.
*
* @return Boolean
*/
ACTIV_ONE_API bool IsValidHandle(const Handle handle) const;
/**
* @brief Get the SHM stats.
*
* Note that fetching these statistics can have a small performance impact.
*
* @return the SHM stats.
*/
ACTIV_ONE_API ShmStats GetShmStats();
private:
const CxxYZ::unique_ptr<SessionImpl> m_pImpl; ///< Private implementation.
template <typename T>
friend class SessionImplBase;
friend class LiteSessionImpl;
friend class StandardSessionImpl;
};
} // namespace OneApi
} // namespace Activ
#endif // (!defined ACTIV_ONE_API_SESSION_H)