/** * @file include/ActivMiddleware/ActivFramework/ServiceApi.h * * @brief Header file for service access api. */ #if (!defined ACTIV_FRAMEWORK_SERVICE_API_H) #define ACTIV_FRAMEWORK_SERVICE_API_H #include "ActivMiddleware/ActivFramework/External.h" #include "ActivMiddleware/ActivFramework/Messages.h" #include "ActivMiddleware/ActivFramework/ServiceTypes.h" //! Activ namespace. namespace Activ { class Component; class HeapMessage; class ScopedAddress; // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief Api to the access services. */ class ServiceApi { public: /** * @brief Add an attribute to the local DirectoryService. * * @param component * @param key the key to add/update. * @param value the (single) value to add to key @a key. * * @return STATUS_CODE_SUCCESS or an error status. */ ACTIV_FRAMEWORK_API static StatusCode AddDirectoryServiceAttribute(const Component &component, const String &key, const String &value); /** * @brief Add an attribute query to the set of attributes we are matching against remote directory services. * * @param component * @param attributeQuery * * @return STATUS_CODE_SUCCESS or an error status. */ ACTIV_FRAMEWORK_API static StatusCode AddRemoteDirectoryServiceAttributeQuery(const Component &component, const String &attributeQuery); /** * @brief Find all instances of a service by service id and return all access points. * * @param component the component doing the find. * @param serviceId id of the service to find. * @param agentScope scope of the services to find (within this agent space or globally). * @param attributeQuery an LDAP style attribute query. Pass empty string to not filter by attributes. * @param serviceInstanceList to receive the results of the find. * @param timeout how long to wait for the response, in ms. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_FOUND * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode FindServices(const Component &component, const ServiceId &serviceId, const AgentScope agentScope, const String &attributeQuery, ServiceInstanceList &serviceInstanceList, const TimeoutPeriod timeout = 5000); /** * @brief Find all instances of a service by service id and return all access points. * * @param component the component doing the find. * @param serviceId id of the service to find. * @param agentScope scope of the services to find (within this agent space or globally). * @param attributeQuery an LDAP style attribute query. Pass empty string to not filter by attributes. * @param serviceOrdering how to order the results. * @param serviceInstanceList to receive the results of the find. * @param timeout how long to wait for the response, in ms. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_FOUND * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode FindServices(const Component &component, const ServiceId &serviceId, const AgentScope agentScope, const String &attributeQuery, const ServiceOrdering serviceOrdering, ServiceInstanceList &serviceInstanceList, const TimeoutPeriod timeout = 5000); /** * @brief Deserialize a notification of a service being registered. * * A service register message has type SERVICE_MESSAGE_REGISTER. * * @param heapMessage * @param serviceInstance to receive details of the service. * * @return STATUS_CODE_SUCCESS or an error status if @a heapMessage couldn't be deserialized. */ ACTIV_FRAMEWORK_API static StatusCode DeserializeServiceRegisterMessage(const HeapMessage &heapMessage, ServiceInstance &serviceInstance); /** * @brief Deserialize a notification of a service being deregistered. * * A service deregister message has type SERVICE_MESSAGE_DEREGISTER. * * @param heapMessage * @param uuid to receive the uuid of the service that is no longer available. * * @return STATUS_CODE_SUCCESS or an error status if @a heapMessage couldn't be deserialized. */ ACTIV_FRAMEWORK_API static StatusCode DeserializeServiceDeregisterMessage(const HeapMessage &heapMessage, Uuid &uuid); /** * @brief Deserialize a notification of a service's attributes being updated. * * A service attribute update message has type SERVICE_MESSAGE_UPDATE_ATTRIBUTES. * * @param heapMessage * @param uuid to receive the uuid of the service. * @param serviceAttributes to receive the new attributes. * * @return STATUS_CODE_SUCCESS or an error status if @a heapMessage couldn't be deserialized. */ ACTIV_FRAMEWORK_API static StatusCode DeserializeServiceAttributesUpdateMessage(const HeapMessage &heapMessage, Uuid &uuid, ServiceAttributes &serviceAttributes); /** * @brief Open a service. * * The m_serviceId member must contain the id of the service you wish to open and the m_url member must * contain the access point of the service you wish to use. * * On a successful return, the m_serviceAddress member will contain the proxied address for communction with the * service. * * If doing an asynchronous open (with timeout == 0), when the connection is established (OnConnect() invoked * with circuitAddress == m_serviceAddress of \a serviceHandle), ValidateOpenServiceResponse() should be called. * This verifies the service connected to is of the right type. * * @param component reference to Component wishing to open service. * @param serviceHandle reference to a ServiceHandle object. * @param timeout how long to wait for the connection to be established, in ms. * @param pOpenServiceRequest optional user data to send in the open service message. * @param pOpenServiceResponse optional data to receive from a sync response. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode OpenService(Component &component, ServiceHandle &serviceHandle, const TimeoutPeriod timeout = COMPONENT_DEFAULT_TIMEOUT, OpenServiceRequest * const pOpenServiceRequest = 0, OpenServiceResponse * const pOpenServiceResponse = 0); /** * @brief Close a service. * * The close is handled asynchronously, as there may be data queued up on the endpoint from the service. * At some point an OnDisconnect() callback will be invoked with circuitAddress == serviceHandle.m_serviceAddress. * * @param component reference to Component that opened the service. * @param serviceHandle reference to a ServiceHandle object as filled in by a successful OpenService(). * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_CONNECTED * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode CloseService(Component &component, const ServiceHandle &serviceHandle); /** * @brief Validate an open service response. * * @param connectMessage as passed to Component::OnConnect(). * @param openServiceResponse to deserialize into. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_FRAMEWORK_API static StatusCode ValidateOpenServiceResponse(const HeapMessage &connectMessage, OpenServiceResponse &openServiceResponse); private: /** * @brief Initiate an asynchronous open service. * * @param component reference to Component wishing to open service. * @param serviceHandle the service to open. * @param pOpenServiceRequest open service request data. * * @retval STATUS_CODE_SUCCESS * @retval ... */ static StatusCode OpenServiceAsync(Component &component, ServiceHandle &serviceHandle, const OpenServiceRequest * const pOpenServiceRequest); /** * @brief Synchronously open a service. * * @param component reference to Component wishing to open service. * @param serviceHandle the service to open. * @param pOpenServiceRequest open service request data. * @param pOpenServiceResponse to receive open response data. * * @retval STATUS_CODE_SUCCESS * @retval ... */ static StatusCode OpenServiceSync(Component &component, ServiceHandle &serviceHandle, const TimeoutPeriod timeout, const OpenServiceRequest * const pOpenServiceRequest, OpenServiceResponse * const pOpenServiceResponse); }; } // namespace Activ #endif // (!defined ACTIV_FRAMEWORK_SERVICE_API_H)