medcrypt::guardian::Session

Individual connection within a Service.

#include <Session.h>

Public Functions

	Name
	~Session() The destructor.
bool	IsReady() Are the underlying channels and tranport ready for operation.
bool	IsFailed() Have the underlying transport or channels failed.
Status	FindChannel(const char in_channel_name, std::unique_ptr< ChannelGuard > out_channelguard) Searches for session channel instance based on provided name.
Status	Shutdown(const bool & in_force =false) Stops contained connection and channelguards, blocking any further data from being queued for send.
Status	DataForSocket(char out_data, size_t io_data_size) Provides data to send over a customer managed transport (blocking)
Status	AsyncDataForSocket(char out_data, size_t io_data_size) Provides data to send over a customer managed transport (non-blocking)
Status	DataFromSocket(const char * in_data, size_t in_data_size) Accepts data to process from a customer managed transport (blocking)
Status	AsyncDataFromSocket(const char * in_data, size_t in_data_size) Accepts data to process from a customer managed transport (non-blocking)
bool	IsDataGone() Indicates if the session has data waiting to be sent.
Status	SetDataForSocketCallback(const std::function< bool(const char *, const size_t &)> & in_callback) Registers a callback for sending data through a user managed transport.
Status	SetDataFromSocketCallback(const std::function< bool(char *, size_t )> & in_callback) Registers a callback for receiving data from a user managed transport.

Public Functions Documentation

function ~Session

~Session()

The destructor.

Parameters:

• none

Return: none

The destructor will not affect the internal Guardian representation of the Session.

function IsReady

bool IsReady()

Are the underlying channels and tranport ready for operation.

Parameters:

• none

Returns:

• true the session and contained channels are ready to send/receive data

• false the session and contained channels are not ready to send/receive data

Return: bool

If the session is ready all contained channels are ready to send and receive data over the contained connected tranport mechanism.

Already received and processed data can still be retrieved through ChannelGuards even if the session is not ready.

function IsFailed

bool IsFailed()

Have the underlying transport or channels failed.

Parameters:

• none

Returns:

• true an error has occurred that is blocking future send/receive operations

• false no error has occurred

Return: bool

If the session is failed, it should be destroyed and recreated with Start

Already received and processed data can still be retrieved through ChannelGuards even if the session is failed.

function FindChannel

Status FindChannel(
    const char * in_channel_name,
    std::unique_ptr< ChannelGuard > * out_channelguard
)

Searches for session channel instance based on provided name.

Parameters:

• in_channel_name null terminated channel name

• out_channelguard pointer to unique_ptr storage for found channelguard

Returns:

• OK the pointer in out_channelguard is valid

• FAIL could not find the channelguard specified by in_channel_name

• BADPARAM in_channel_name is nullptr or empty or out_channelguard is nullptr

Return: medcrypt::guardian::Status

Uses the loaded profile to secure and/or enable authentication based on unmanged service configuration for the provided transport.

function Shutdown

Status Shutdown(
    const bool & in_force =false
)

Stops contained connection and channelguards, blocking any further data from being queued for send.

Parameters:

• in_force after the timeout (or immediately if the timeout is 0) drop all waiting data and shutdown.

Returns:

• OK session is shutdown

• FAIL general failure, check the log

• AGAIN one or more transports has queued data to send

Return: medcrypt::guardian::Status

Includes all contained channelguard and any contained transport, even those that have been placed or had a parent placed on another thread by CreateTask.

function DataForSocket

Status DataForSocket(
    char * out_data,
    size_t * io_data_size
)

Provides data to send over a customer managed transport (blocking)

Parameters:

• out_data binary data buffer to store output data

• io_data_size provide size of provided out_data buffer, on successful return is set to size of the data in out_data, on failure is set to 0

Returns:

• OK out_data is populated with data to send

• FAIL general failure, check the log

• BADPARAM out_data is nullptr or io_data_size is nullptr or 0

• DENIED session is managed

• OUTOFMEMORY provided buffer too small

Return: medcrypt::guardian::Status

Blocking call only applicable to unmanaged service sessions. out_data should be a user allocated buffer to store data intended to be sent over the user managed transport. The call will return immediately under any of the below error conditions, otherwise it will block until data is ready to send.

function AsyncDataForSocket

Status AsyncDataForSocket(
    char * out_data,
    size_t * io_data_size
)

Provides data to send over a customer managed transport (non-blocking)

Parameters:

• out_data binary data buffer to store output data

• io_data_size provide size of provided out_data buffer, on successful return is set to size of the data in out_data, on failure is set to 0

Returns:

• OK out_data is populated with data to send

• FAIL general failure, check the log

• BADPARAM out_data is nullptr or io_data_size is nullptr or 0

• DENIED session is managed

• OUTOFMEMORY provided buffer too small

• AGAIN there is no data waiting to send, out_data unmodified

Return: medcrypt::guardian::Status

Non-blocking call only applicable to unmanaged service sessions. out_data should be a user allocated buffer to store data intended to be sent over the user managed transport.

function DataFromSocket

Status DataFromSocket(
    const char * in_data,
    size_t in_data_size
)

Accepts data to process from a customer managed transport (blocking)

Parameters:

• in_data_size size of binary data in in_data

• in_data binary data buffer of received data

Returns:

• OK in_data has been processed

• FAIL unable to process in_data

• DENIED session is managed

• OUTOFMEMORY provided buffer is too large to send

Return: medcrypt::guardian::Status

Blocking call only applicable to unmanaged service sessions. in_data should contain information received from a customer managed transport. On return data will be available for retrieval from a channelguard.

function AsyncDataFromSocket

Status AsyncDataFromSocket(
    const char * in_data,
    size_t in_data_size
)

Accepts data to process from a customer managed transport (non-blocking)

Parameters:

• in_data_size size of binary data in in_data

• in_data binary data buffer of received data

Returns:

• OK in_data has been queued for processing or processed

• FAIL unable to process in_data

• DENIED session is managed

• OUTOFMEMORY provided buffer is too large

Return: medcrypt::guardian::Status

Non-blocking call only applicable to unmanaged service sessions. in_data should contain information received from a customer managed transport. On return data will may be availble for retrieval from a channelguard.

function IsDataGone

bool IsDataGone()

Indicates if the session has data waiting to be sent.

Parameters:

• none

Returns:

• false data is waiting to be sent

• true no data is waiting to be sent

Return: bool

If false there is data waiting to be sent over the contained managed transport or retrieved using [Async]DataForSocket to be sent over a user managed transport. If false AsyncDataForSocket will return OK and DataForSocket will not block. No guarantees are made on if a non-forcing Shutdown call will block since in a multi-threaded environment more data could be queued for send between a call to IsDataGone and Shutdown.

function SetDataForSocketCallback

Status SetDataForSocketCallback(
    const std::function< bool(const char *, const size_t &)> & in_callback
)

Registers a callback for sending data through a user managed transport.

Parameters:

• in_callback blocking function that will send data over the user managed transport when called,returns false on failure.

Returns:

• OK callback registered

• FAIL general failure

• DENIED session is managed

Return: medcrypt::guardian::Status

Provides a callback for use with user managed transport and blocking ChannelGuard calls. The provided function must be a blocking call and return only when data has been successfully sent or a failure makes it impossible to send the data.

function SetDataFromSocketCallback

Status SetDataFromSocketCallback(
    const std::function< bool(char **, size_t *)> & in_callback
)

Registers a callback for receiving data from a user managed transport.

Parameters:

• in_callback blocking function that will receive data from the user managed transport when called, returns false on failure.

Returns:

• OK callback registered

• FAIL general failure

• DENIED session is managed

Return: medcrypt::guardian::Status

Provides a callback for use with user managed transport and blocking ChannelGuard calls. The provided function must be a blocking call and return only when data has been successfully received or a failure makes it impossible to receive data. The callback should follow the same rules for the size_t parameters as DataFromSocket.

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.