> For the complete documentation index, see [llms.txt](https://docs.medcrypt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.medcrypt.com/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-service.md). # medcrypt::guardian::Service ## Overview This is a named group of connection and channel configurations. **Usage:** This class is used to manage network connections and communication channels in Guardian applications. **Include:** ```cpp #include ``` **Syntax:** ```cpp struct medcrypt::guardian::utilities::ProvisionOnlineFiles; ``` ### Public functions * [\~Service](#function-~service): This is the destructor. * [IsReady](#function-isready): Checks whether service is ready for operation. * [IsFailed](#function-isfailed): Checks whether the service in a failed state. * [Listen](#function-listen): Allows a managed server service to listen for new connections. * [ConfigureTransport](#function-configuretransport): Secures the provided transport based on the loaded profile. * [Shutdown](#function-shutdown): Stops all contained connections, blocking for any queued data to send or fail to send. * [Start](#function-start) (no override): Starts connection. This is blocking. * [Start](#start-with-override) (with override): Starts connection using the provided override string. This is blocking. * [AsyncStart](#function-asyncstart): Starts connection. This is non-blocking. * [AsyncStart](#asyncstart-with-override): Starts connection using the provided override string. This is non-blocking. * [ClientWaiting](#function-clientwaiting): Checks whether a client is waiting to connect. This is non-blocking. ### Function details #### \~Service() * **Description:** The destructor will not affect the internal [Guardian](/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-guardian.md) representation of the [Service](/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-service.md).. * **Dependencies:** None - destructor is called automatically * **Parameters:** None - destructor takes no parameters * **Returns:** Nothing since it is a destructor. * **Action:** Cleans up service resources without affecting Guardian's internal representation. * **Syntax:** ```cpp ~Service() ``` #### IsReady() * **Description:** Check if the service is ready for operation. * **Dependencies:** Must be called after service is created * **Parameters:** None * **Returns:** Boolean value indicating service readiness * `true` - Service is ready for its configured operations * `false` - Service is not ready or is a server service that is not listening * **Action:** * **For client/unmanaged services:** Ready to create new sessions using [Start](#function-start) asynchronously. * **For server services:** Transport is listening and ready to accept connections. * **Syntax:** ```cpp bool IsReady() ``` #### IsFailed() * **Description:** Used for server services when underlying transport fails during listening. Checks if the service is in a failed state. * **Dependencies:** Used for server services to check transport status * **Parameters:** None * **Returns:** Boolean value indicating failure state * `true` - The underlying server transport has failed * `false` - The underlying server transport has not failed * **Action:** Service should be shutdown and [Listen](#function-listen) called again. * **Syntax:** ```cpp bool IsFailed() ``` #### Listen() * **Description:** * Allows a managed server service to listen for new connections. * Equivalent to calling 'bind' and 'listen' on a server socket. * This function is not applicable to unmanaged or client services. * **Dependencies:** Only applicable to managed server services * **Parameters:** * `in_override`: Null terminated transport specific override string * **Default value:** nullptr (no override) * **Returns:** Status code indicating success or failure. * **Success code:** `OK` - Successfully started listening for connections * **Error codes:** * `FAIL` - General failure, did not start listening for connections * `MISCONFIGURED` - Service is configured as unmanaged or as a a client * **Action:** * Starts listening for incoming connections on configured transport. * **Example:** zeromq ex: "tcp\://127.0.0.1:12345" * (default: no override) * **See also:** "Override Strings" documentation * **Syntax:** ```cpp Status Listen( const char * in_override =nullptr ) ``` #### ConfigureTransport() * **Description:** * Secures the provided transport based on the loaded profile. * Uses profile configuration to secure and/or enable authentication for the provided transport based on unmanaged service configuration. * **Dependencies:** Must have loaded profile with transport configuration * **Parameters:** * `in_transport`: Transport to be configured * **Returns:** Status code indicating success or failure. * **Success code:** `OK` - Successfully configured provided transport * **Error codes:** * `FAIL` - General failure, transport is unconfigured * `BADPARAM` - `in_transport` is empty * `MISCONFIGURED` - Profile does not support configuring transport on this service * `HANDSHAKEREQUIRED` - Current CertificateManager lacks necessary keys/trust * **See also:** "Unmanaged Handshaking" documentation * **Action:** Applies security configuration from profile to the provided transport. * **See also:** "Unmanaged Handshaking" documentation. * **Syntax:** ```cpp Status ConfigureTransport( std::shared_ptr< TransportInterface > in_transport ) ``` #### Shutdown() * **Description:** * Stops all contained connections, blocking for any queued data to send or fail to send. * Includes all sessions, connections, and channels, even those placed on other threads by [CreateTask](/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-guardian.md#function-createtask). * **Dependencies:** Can be called on active service * **Parameters:** * `in_force`: After the timeout (or immediately if the timeout is 0), drop all waiting data and shut down. * **Default value:** `false` * **Returns:** Status code indicating success or failure. * **Success code:** `OK` - Service is shut down * **Error codes:** * `FAIL` - General failure. Check the log. * `AGAIN` - One or more transports has queued data to send * **Action:** Stops all contained connections and cleans up resources. * **Syntax:** ```cpp Status Shutdown( const bool & in_force =false ) ``` #### Start(): No override * **Description:** * Starts connection via blocking call. * Behavior varies by service type: * **Managed:** * **Client services:** Block until connection succeeds/fails. * **Server services:** Block until client connects. * **Unmanaged services:** Always succeed unless transport configuration is required and no transport has been provided. * **Dependencies:** Service must be ready and properly configured * **Parameters:** * `out_session`: Pointer populated with resulting session on success * **Returns:** Status code indicating success or failure. * **Success code:** `OK` - Successfully started a connection * **Error codes:** * `FAIL` - Could not connect to endpoint or server service was shut down * `BADPARAM` - `out_session` is null pointer * `MISCONFIGURED` - Profile has insufficient data to create connection * **Action:** Creates and establishes a connection, returning a session object. * **Syntax:** ```cpp Status Start( std::unique_ptr< Session > * out_session ) ``` #### Start(): With override * **Description:** * Blocking call to create connection using provided override string. * Not applicable to server services. * **Dependencies:** Service must support override strings * **Parameters:** * `in_override`: Transport specific override string, terminated by null * `out_session`: Pointer populated with resulting session on success * **Returns:** Status code indicating success or failure. * **Success code:** `OK` - Successfully started a connection * **Error codes:** * `FAIL` - Could not connect to endpoint or server service was shutdown * `BADPARAM` - out\_session is null pointer * `MISCONFIGURED` - Profile has insufficient data or unmanaged connection needs configured transport * `DENIED` - This is a server service, override not possible * **See also:** All status codes for complete reference * **Action:** Creates connection using custom transport parameters. * **Syntax:** ```cpp Status Start( const char * in_override, std::unique_ptr< Session > * out_session ) ``` Starts connection using the provided override string(blocking). **Parameters**: * **in\_override** null terminated transport specific override string see "Override Strings" documentation. zeromq ex: "tcp\://127.0.0.1:12345", defaults to no override * **out\_session** on success this pointer is populated with the resulting session **Returns**: * **OK** successfully started a connection * **FAIL** could not connect to endpoint or server service was shutdown * **BADPARAM** out\_session is nullptr * **MISCONFIGURED** profile has insufficient data to create a connection OR this is an unmanaged connection that needs a configured transport * **DENIED** this is a server service, an override is not possible **Return**: [medcrypt::guardian::Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) Blocking call to create a connection. Managed: Client: Will block until a connection succeeds or fails. Server: Not applicable. Unmanaged: This call will always succeed unless the loaded profile requires a configured transport and no transport has been provided. #### AsyncStart() * **Description:** Non-blocking call to create connection. Client services return once connection process begins. Server services return waiting client if available. Unmanaged services equivalent to Start(). * **Dependencies:** Service must be ready for connections * **Parameters:** * `out_session`: Pointer populated with resulting session on success * **Returns:** Status code indicating success or failure. * **Success code:** `OK` - Successfully started the connection process * **Error codes:** * `FAIL` - Could not connect to endpoint * `BADPARAM` - out\_session is null pointer * `MISCONFIGURED` - Profile has insufficient data to create connection * `AGAIN` - Server only, no client waiting to connect * **See also:** All status codes for complete reference * **Action:** Initiates connection process without blocking. * **Syntax:** #### AsyncStart() - With Override * **Description:** Non-blocking call to create connection using override string. Not applicable to server services already listening. * **Dependencies:** Service must support override and not be listening server * **Parameters:** * `in_override`: Transport specific override string, terminated by null * `out_session`: Pointer populated with resulting session on success * **Returns:** Status code indicating success or failure. * **Success code:** `OK` - Successfully started a connection * **Error codes:** * `FAIL` - Could not connect to endpoint * `BADPARAM` - out\_session is null pointer * `MISCONFIGURED` - Profile has insufficient data to create connection * `DENIED` - Server service already listening, override not possible * `AGAIN` - Server only, no client waiting to connect * **See also:** All status codes for complete reference * **Action:** Initiates connection with custom parameters without blocking. **Syntax:** #### ClientWaiting() * **Description:** Check if a client is waiting to connect (non-blocking). Always returns false for client services. * **Dependencies:** Only relevant for server services * **Parameters:** None * **Returns:** Boolean value indicating client availability * `true` - There is a client waiting * `false` - No client waiting or this is a client service * **Action:** If true, AsyncStart() will succeed and Start() will not block. * **Syntax:** | | Name | | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | |

\~Service()
The destructor.

| | bool |

IsReady()
Is the service ready for operation.

| | bool |

IsFailed()
Is the service in a failed state.

| | [Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

Listen(const char \* in\_override =nullptr)
Allows a managed server service to listen for new connections.

| | [Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

ConfigureTransport(std::shared\_ptr< TransportInterface > in\_transport)
Secures the provided transport based on the loaded profile.

| | [Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

Shutdown(const bool & in\_force =false)
Stops all contained connections, blocking for any queued data to send or fail to send.

| | [Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

Start(std::unique\_ptr< Session > \* out\_session)
Starts connection (blocking).

| | [Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

Start(const char in\_override, std::unique\_ptr< Session > out\_session)
Starts connection using the provided override string(blocking).

| | [Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

AsyncStart(std::unique\_ptr< Session > \* out\_session)
Starts connection (non-blocking).

| | [Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

AsyncStart(const char in\_override, std::unique\_ptr< Session > out\_session)
Starts connection using the provided override string (non-blocking).

| | bool |

ClientWaiting()
Check if a client is waiting to connect (non-blocking)

| ## Public Functions Documentation ### function Start ```cpp Status Start( std::unique_ptr< Session > * out_session ) ``` Starts connection (blocking). **Parameters**: * **out\_session** on success this pointer is populated with the resulting session **Returns**: * **OK** successfully started a connection * **FAIL** could not connect to endpoint or server service was shutdown * **BADPARAM** out\_session is nullptr * **MISCONFIGURED** profile has insufficient data to create a connection **Return**: [medcrypt::guardian::Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) Blocking call to create a connection. Managed: Client: Will block until a connection succeeds or fails. Server: Will block until a client connects. Unmanaged: This call will always succeed unless the loaded profile requires a configured transport and no transport has been provided. ### function Start ```cpp Status Start( const char * in_override, std::unique_ptr< Session > * out_session ) ``` Starts connection using the provided override string(blocking). **Parameters**: * **in\_override** null terminated transport specific override string see "Override Strings" documentation. zeromq ex: "tcp\://127.0.0.1:12345", defaults to no override * **out\_session** on success this pointer is populated with the resulting session **Returns**: * **OK** successfully started a connection * **FAIL** could not connect to endpoint or server service was shutdown * **BADPARAM** out\_session is nullptr * **MISCONFIGURED** profile has insufficient data to create a connection OR this is an unmanaged connection that needs a configured transport * **DENIED** this is a server service, an override is not possible **Return**: [medcrypt::guardian::Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) Blocking call to create a connection. Managed: Client: Will block until a connection succeeds or fails. Server: Not applicable. Unmanaged: This call will always succeed unless the loaded profile requires a configured transport and no transport has been provided. ### function AsyncStart ```cpp Status AsyncStart( std::unique_ptr< Session > * out_session ) ``` Starts connection (non-blocking). **Parameters**: * **out\_session** on success this pointer is populated with the resulting session **Returns**: * **OK** successfully started the connection process * **FAIL** could not connect to endpoint * **BADPARAM** out\_session was set to nullptr * **MISCONFIGURED** profile has insufficient data to create a connection * **AGAIN** server only, no client waiting to connect, try again **Return**: [medcrypt::guardian::Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) Non-blocking call to create a connection. Managed: Client: Will return once the underlying connection process has begun or failed. Server: return a waiting client connection if available. Unmanaged: Equivalent to calling Start. ### function AsyncStart ```cpp Status AsyncStart( const char * in_override, std::unique_ptr< Session > * out_session ) ``` Starts connection using the provided override string (non-blocking). **Parameters**: * **in\_override** null terminated transport specific override string see "Override Strings" documentation. zeromq ex: "tcp\://127.0.0.1:12345", defaults to no override * **out\_session** on success this pointer is populated with the resulting session **Returns**: * **OK** successfully started a connection * **FAIL** could not connect to endpoint * **BADPARAM** out\_session was set to nullptr * **MISCONFIGURED** profile has insufficient data to create a connection * **DENIED** this is a server service that is already listening and an override is not possible * **AGAIN** server only, no client waiting to connect, try again **Return**: [medcrypt::guardian::Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) Non-blocking call to create a connection. Managed: Client: Will return once the underlying connection process has begun or failed. Server: Not applicable. Unmanaged: Equivalent to calling Start. ### function ClientWaiting ```cpp bool ClientWaiting() ``` Check if a client is waiting to connect (non-blocking) **Parameters**: * **none** **Returns**: * **true** there is a client waiting * **false** there is not a client waiting or this is a client service **Return**: bool If true Async start will succeed and Start will not block. Will always return false for a client service. ## Debugging and logging Guardian does not create log files. Instead, logging is controlled by the application: * Guardian logs to `stdout` and `stderr`, which appear in the terminal/CLI of the running application during execution. Look for specific error codes or connection failures in the output. * **Custom logging:** Use `SetLoggingCallback` to redirect log messages to a callback function, stopping terminal output and allowing custom log handling * **Log control:** Applications can control log level and verbosity. * **Guardian Cloud UI**: Check the Guardian Cloud interface for additional error details and provisioning status. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.medcrypt.com/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-service.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.