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:

#include <Service.h>

Syntax:

struct medcrypt::guardian::utilities::ProvisionOnlineFiles;

Public functions

• ~Service: This is the destructor.

• IsReady: Checks whether service is ready for operation.

• IsFailed: Checks whether the service in a failed state.

• Listen: Allows a managed server service to listen for new connections.

• ConfigureTransport: Secures the provided transport based on the loaded profile.

• Shutdown: Stops all contained connections, blocking for any queued data to send or fail to send.

• Start (no override): Starts connection. This is blocking.

• Start (with override): Starts connection using the provided override string. This is blocking.

• AsyncStart: Starts connection. This is non-blocking.

• AsyncStart: Starts connection using the provided override string. This is non-blocking.

• 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 representation of the Service..

• 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:

~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 asynchronously.

  • For server services: Transport is listening and ready to accept connections.

• Syntax:

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 called again.

• Syntax:

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:

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:

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.

• 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:

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:

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:

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

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	Listen(const char * in_override =nullptr) Allows a managed server service to listen for new connections.
Status	ConfigureTransport(std::shared_ptr< TransportInterface > in_transport) Secures the provided transport based on the loaded profile.
Status	Shutdown(const bool & in_force =false) Stops all contained connections, blocking for any queued data to send or fail to send.
Status	Start(std::unique_ptr< Session > * out_session) Starts connection (blocking).
Status	Start(const char in_override, std::unique_ptr< Session > out_session) Starts connection using the provided override string(blocking).
Status	AsyncStart(std::unique_ptr< Session > * out_session) Starts connection (non-blocking).
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

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

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

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

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

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

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

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

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

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.