/** * @file include/ActivMiddleware/ActivFramework/PubSubServiceApi.h * * @brief Header file for the pubsub service api. */ #if (!defined ACTIV_FRAMEWORK_PUB_SUB_SERVICE_API_H) #define ACTIV_FRAMEWORK_PUB_SUB_SERVICE_API_H #include "ActivMiddleware/ActivFramework/External.h" #include "ActivMiddleware/ActivBase/FieldTypes/UInt.h" #include "ActivMiddleware/ActivBase/ProcessorAffinity.h" #include "ActivMiddleware/ActivFramework/Subject.h" #include #include #include //! Activ namespace. namespace Activ { class Address; class Component; class HeapMessage; class MessageBuilder; class PostMessageHelper; class Subject; // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief Api to the agent's pubsub service. */ class PubSubServiceApi { public: typedef std::set
AddressSet; ///< address set type typedef std::vector AddressSetList; ///< address set list. Index is AgentScope typedef std::map SubscriptionMap; ///< subscription map /** * @brief Multicast settings. * * This describes an instance of a multicast input/output. */ class Multicast { public: //! Compression types. enum CompressionType { COMPRESSION_TYPE_NONE, COMPRESSION_TYPE_NULL, COMPRESSION_TYPE_RDC, COMPRESSION_TYPE_ZLIB, NUM_COMPRESSION_TYPES ///< Number of compression types. }; //! Default constructor. ACTIV_FRAMEWORK_API Multicast(); String m_url; ///< Of the form: apd://multicast-group:port. String m_interfaceAddress; ///< Local interface to bind to. UInt m_socketTxBufferSize; ///< Default undefined; leave as OS default. UInt m_socketRxBufferSize; ///< Default 1MB. uint16_t m_flushByteThreshold; ///< Default: 1472. Flush tx buffer when >= this; set to the MTU if 0. TimeoutPeriod m_blockingTimeout; ///< Default 50ms. bool m_shouldTransmit; ///< Transmit on this group? Default true. bool m_shouldListen; ///< Receive on this group? Default false. size_t m_ttl; ///< Ttl for transmission. Default is 4. CompressionType m_txCompressionType; ///< Default COMPRESSION_TYPE_NONE. ProcessorAffinity m_threadProcessorAffinity; ///< Default: do not adjust. }; /** * @brief Subscribe to a subject. * * Note subscriptions from a component are not cumulative at the same scope level. However, subscribing to the * same subject at more than one scope requires unsubscribing at each scope. * * @param component the component wishing to subscribe. * @param agentScope AGENT_SCOPE_LOCAL only receive messages published within this agent space, * AGENT_SCOPE_GLOBAL receive both local and messages published onto the network, AGENT_SCOPE_REMOTE only receive * messages published remotely. * @param subject subject to subscribe to. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode Subscribe(const Component &component, const AgentScope agentScope, const Subject &subject); /** * @brief Unsubscribe from a subject. * * @param component the component wishing to unsubscribe. * @param agentScope the scope from which to unsubscribe. * @param subject the subject to unsubscribe from. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode Unsubscribe(const Component &component, const AgentScope agentScope, const Subject &subject); /** * @brief Publish a message. * * @param component the component wishing to publish. * @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE * only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely. * @param subject subject of published message. * @param type type of published message. * @param messageBuilder reference to a MessageBuilder containing the message body to publish. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, const AgentScope agentScope, const Subject &subject, const MessageType type, const MessageBuilder &messageBuilder); /** * @brief Publish a message. * * @param component the component wishing to publish. * @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE * only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely. * @param subject subject of published message. * @param type type of published message. * @param pData pointer to message body. * @param dataLength length of message body. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, const AgentScope agentScope, const Subject &subject, const MessageType type, const void *pData = 0, const size_t dataLength = 0); /** * @brief Publish a message. * * @param component the component wishing to publish. * @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE * only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely. * @param subject subject of published message. * @param type type of published message. * @param heapMessage HeapMessage containing message body to publish. * * @retval STATUS_CODE_SUCCESS. heapMessage will no longer have a message attached. * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, const AgentScope agentScope, const Subject &subject, const MessageType type, HeapMessage &heapMessage); /** * @brief Publish a message via a PostMessageHelper object. * * @param component the component wishing to publish. * @param postMessageHelper reference to a PostMessageHelper. The published message will be queued here * and not immediately sent to the PubSubService for distribution. postMessageHelper.Flush() will * need to be called at some point in order to push any queued messages to the PubSubService. * @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE * only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely. * @param subject subject of published message. * @param type type of published message. * @param messageBuilder reference to a MessageBuilder containing the message body to publish. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_HEAP_EMTPY */ ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, PostMessageHelper &postMessageHelper, const AgentScope agentScope, const Subject &subject, const MessageType type, const MessageBuilder &messageBuilder); /** * @brief Publish a message via a PostMessageHelper object. * * @param component the component wishing to publish. * @param postMessageHelper reference to a PostMessageHelper. The published message will be queued here * and not immediately sent to the PubSubService for distribution. postMessageHelper.Flush() will * need to be called at some point in order to push any queued messages to the PubSubService. * @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE * only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely. * @param subject subject of published message. * @param type type of published message. * @param pData pointer to message body. * @param dataLength length of message body. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_HEAP_EMTPY */ ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, PostMessageHelper &postMessageHelper, const AgentScope agentScope, const Subject &subject, const MessageType type, const void *pData = 0, const size_t dataLength = 0); /** * @brief Publish a message via a PostMessageHelper object. * * @param component the component wishing to publish. * @param postMessageHelper reference to a PostMessageHelper. The published message will be queued here * and not immediately sent to the PubSubService for distribution. postMessageHelper.Flush() will * need to be called at some point in order to push any queued messages to the PubSubService. * @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE * only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely. * @param subject subject of published message. * @param type type of published message. * @param heapMessage HeapMessage containing message body to publish. */ ACTIV_FRAMEWORK_API static void Publish(const Component &component, PostMessageHelper &postMessageHelper, const AgentScope agentScope, const Subject &subject, const MessageType type, HeapMessage &heapMessage); /** * @brief Get subscriptions. * * @param component the component requesting subscriptions. * @param subject the subject to get the subscriptions for. * @param shouldRecurseTree whether to get subscriptions for entire subject tree. * @param subscriptionMap reference to the subscription map to receive subscriptions. * @param timeout timeout in ms. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode GetSubscriptions(const Component &component, const Subject &subject, const bool shouldRecurseTree, SubscriptionMap &subscriptionMap, const TimeoutPeriod timeout = COMPONENT_DEFAULT_TIMEOUT); /** * @brief Add a multicast input/output. * * If the provided name is already configured as a multicast output, an error is returned. * * @param component * @param name a name for the multicast. * @param multicast describing the group, port, interface, etc. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode AddMulticast(const Component &component, const String &name, const Multicast &multicast); /** * @brief Republish a Subject on a given named multicast output. * * @param component * @param subject the Subject to publish output on the multicast @a multicastName. * @param multicastName as passed to AddMulticast() or from static configuration of the PubSubService. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode AddSubjectToMulticast(const Component &component, const Subject &subject, const String &multicastName); /** * @brief Append a trailing Subject::SEPARATOR_CHAR to a subject if required. * * @param subject subject string to modify in-place. * * @return false if the subject is invalid. */ ACTIV_FRAMEWORK_API static bool BuildFullyQualifiedSubject(String &subject); }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief Scoped subscription helper. */ class ScopedSubscription : private Boost::noncopyable { public: /** * @brief Constructor. * * @param component */ ACTIV_FRAMEWORK_API ScopedSubscription(const Component &component); /** * @brief Constructor. * * Subscribes the component to the given subject at the given scope. * * @param component * @param agentScope * @param subject * * @throw Exception if unable to subscribe. */ ACTIV_FRAMEWORK_API ScopedSubscription(const Component &component, const AgentScope agentScope, const Subject &subject); /** * @brief Destructor. * * Unsubscribes if the subscription is still in place. */ ACTIV_FRAMEWORK_API ~ScopedSubscription(); /** * @brief Subscribes. Will unsubscribe if already subscribed. * * @return STATUS_CODE_SUCCESS or reason for failed subscription. */ ACTIV_FRAMEWORK_API StatusCode Subscribe(const AgentScope agentScope, const Subject &subject); /** * @brief Unsubscribes. * * @return STATUS_CODE_SUCCESS or reason for failed unsubscription. */ ACTIV_FRAMEWORK_API StatusCode Unsubscribe(); //! Is subscribed. bool IsSubscribed() const; private: const Component & m_component; AgentScope m_agentScope; Subject m_subject; bool m_isSubscribed; }; // --------------------------------------------------------------------------------------------------------------------------------- inline bool ScopedSubscription::IsSubscribed() const { return m_isSubscribed; } } // namespace Activ #endif // (!defined ACTIV_FRAMEWORK_PUB_SUB_SERVICE_API_H)