/** * @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 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 ¶meters = 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 ¶meters, 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 ¶meters, 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 ¶meters, 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 ¶meters, 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 ¶meters, 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 m_pImpl; ///< Private implementation. template friend class SessionImplBase; friend class LiteSessionImpl; friend class StandardSessionImpl; }; } // namespace OneApi } // namespace Activ #endif // (!defined ACTIV_ONE_API_SESSION_H)