> 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-session.md). # medcrypt::guardian::Session Individual connection within a [Service](/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-service.md). `#include ` ## 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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

FindChannel(const char in\_channel\_name, std::unique\_ptr< ChannelGuard > out\_channelguard)
Searches for session channel instance based on provided name.

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

Shutdown(const bool & in\_force =false)
Stops contained connection and channelguards, blocking any further data from being queued for send.

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

DataForSocket(char out\_data, size\_t io\_data\_size)
Provides data to send over a customer managed transport (blocking)

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

AsyncDataForSocket(char out\_data, size\_t io\_data\_size)
Provides data to send over a customer managed transport (non-blocking)

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

DataFromSocket(const char \* in\_data, size\_t in\_data\_size)
Accepts data to process from a customer managed transport (blocking)

| | [Status](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-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 ```cpp ~Session() ``` The destructor. **Parameters**: * **none** **Return**: none The destructor will not affect the internal [Guardian](/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-guardian.md) representation of the [Session](/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-session.md). ### function IsReady ```cpp 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 ```cpp 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 ```cpp 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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) Uses the loaded profile to secure and/or enable authentication based on unmanged service configuration for the provided transport. ### function Shutdown ```cpp 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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-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 ```cpp 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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-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 ```cpp 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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-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 ```cpp 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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-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 ```cpp 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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-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 ```cpp 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 ```cpp 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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) Provides a callback for use with user managed transport and blocking [ChannelGuard](/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-channelguard.md) 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 ```cpp 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](/medcrypt-documentation/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) Provides a callback for use with user managed transport and blocking [ChannelGuard](/medcrypt-documentation/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-channelguard.md) 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. --- # 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-session.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.