# API overview ## Provisioning functions ### Guardian() **Description:** Creates new Guardian instance and puts it into startup state, ready for initialization. * First step before any other operations * This constructor only initializes member variables **Dependencies:** None - this is the first function to call **Parameters:** None - default constructor takes no parameters **Returns:** Nothing since it is a constructor **Syntax:** ```cpp Guardian() ``` ### Initialize() **Description:** Initializes Guardian with device credentials and configuration files. Uses the provided profile, identity, and trust files to initialize the Guardian system. **Dependencies:** * Must be called after [creating a Guardian instance](#guardian) (`Guardian()` constructor). * Must be called before any other Guardian operations **Parameters:** * `in_files`: Device credentials and configuration files * `in_component_handle`: This is the unique component identifier used for provisioning. * **Type:** `const char*` * `in_hardware_identifier`: This is the unique hardware identifier. * **Character limitations:** 36 (37 with null terminator) * **Type:** `const char*` * `in_options`: Additional initialization configuration options **Returns:** Status code indicating success or failure. * **Success code:** `OK`**.** Guardian system was successfully initialized. * **Error codes:** * `FAIL`: General failure. Guardian did not initialize successfully. Check the log file for more information. * `BADPARAM`: One of the inputs is null or empty. * `FILENOTFOUND`: A required input file is unavailable. * `OUTOFMEMORY` **:** Not enough memory to initialize Guardian. **Syntax** ```cpp Status Initialize( const utilities::InitializeFiles & in_files, const char * in_component_handle, const char * in_hardware_identifier, const InitializeOptions & in_options ) ``` ## GenerateProvisionRequest() **Description:** The `GenerateProvisionRequest()` function creates provisioning request (`.mcpr`) and private identity (`.mcpi`) files. * This is the first provisioning step for the provisioning process. * This is the only step in the offline provisioning process. * The private identity (`.mcpi` file) includes the generated device keys. * The provision request (`.mcpr` file) can be manually uploaded to Guardian Cloud or sent using available online methods in the profile. **Dependencies:** * Must be called after `Initialize()` * Must be called once before any other provisioning or re-provisioning actions occur. * Required before `StartProvisioningOnline()` **Parameters:** * `io_files` : Provisioning files structure.\ `in_provisioning_component_handle` : This is the unique component identifier used for provisioning. * **Type:** `const char*` * `in_provisioning_system` : This is the unique system name identifier which is sent to Guardian Cloud. * **Character limitations:** 36 (37 with null terminator) * **Type:** `const char*` * `in_hardware_identifier` - This is the unique hardware identifier. * **Character limitations:** 36 (37 with null terminator) * **Type:** `const char*` **Returns:** Status code indicating success or failure. * **Success code:** `OK`**.** Provisioning request was successfully created * **Error codes:** * `FAIL`: General failure. Check the log file for more information. * `BADPARAM`: One of the inputs is null or empty * `FILENOTFOUND`: A required input file is unavailable * `NOWRITE`: A required output file could not be written * `OUTOFMEMORY` : Not enough memory to provision \\ **Syntax** ```cpp Status GenerateProvisionRequest( utilities::ProvisionFiles & io_files, const char * in_provisioning_component_handle, const char * in_provisioning_system, const char * in_hardware_identifier ) ``` ## StartProvisioningOnline() The `StartProvisioningOnline()` function starts the online provisioning process to submit a provisioning request to Guardian Cloud. It submits the provisioning request and begins the automated processing workflow. * **Dependencies:** Must be run after GenerateProvisionRequest(). * **Parameters:** * `in_files`: Files required for online provisioning * `in_options`: Additional optional provisioning configuration options, including timeouts * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : Online provisioning was successfully started * **Error codes:** * `FAIL` : General failure starting provisioning. Check the log file for more information. * `BADPARAM` : One of the inputs is null or invalid * `FILENOTFOUND` : A required provisioning file is unavailable **Syntax** ```cpp Status StartProvisioningOnline( const utilities::ProvisionOnlineFiles & in_files, const ProvisioningOptions & in_options ) ``` ### Run() * **Description:** * Executes Guardian background tasks including provisioning state machine processing. * Includes provisioning, telemetry, handshakes, authentication, services, sessions, and channels that have not been placed or had a parent placed on another thread by [CreateTask](#function-createtask). This should be called by the program/thread's main loop. * Must be called regularly and repeatedly during online provisioning. * Use [IsProvisioningRunning()](#function-isprovisioningrunning) to check when provisioning is complete and stop calling Run(). * Processes internal state machines and handles communication with Guardian Cloud * **Dependencies:** * Must be called after StartProvisioningOnline() * **Parameters:** No parameters * **Returns:** Status code indicating success or failure. * **Success code:** `OK` - Background tasks executed successfully * **Error codes:** * `FAIL` - General failure in background processing. Check the log file for more information. * `SHUTDOWN` : Guardian is in a shutdown state and must be reinitialized before calling run again. ### IsProvisioningRunning() * **Description:** Checks whether the provisioning process is still active. * **Dependencies:** * Must be called after StartProvisioningOnline() * Used to determine when to stop calling Run() and attempt to retrieve the provisioned profile. * **Parameters:** None - this function takes no parameters * **Returns:** Boolean value indicating provisioning status * `true` - Provisioning is still in progress. Continue calling Run() * `false` - Provisioning has completed (successfully or failed). You should now call GetProvisionedProfile(). * Before the online provisioning process has started, will return `false`. * After online provisioning has either succeeded or failed, will again return `false`. **Syntax** ```cpp bool IsProvisioningRunning() ``` ### GetProvisionedProfile() * **Description:** * Extracts the provisioned profile after successful online provisioning. * Copies completed provisioned profile to provided buffer. * **Dependencies:** * Must be called only after IsProvisioningRunning() returns `false`. * Requires successful completion of StartProvisioningOnline() and Run() loop * **Parameters:** * `out_profile`: Buffer that will receive the provisioned profile. * Type: `char` * `io_size`: * Provide size of buffer ( `out_profile` ) on input. After successful provisioning, `out_profile` sets to actual size of profile. * Type: `size_t` * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : Provisioned profile successfully retrieved. * Buffer contains a valid certified profile in `out_profile` of size `io_size`. * **Error codes:** * `FAIL` : General failure. Check the log file for more information. * `INCOMPLETE` : Provisioning process did not complete, thus no profile is available. * `BADPARAM` - `out_profile` or `io_size` is null pointer (`nullptr`), or `io_size` is 0 * `DENIED` - Online provisioning process is still running * `FILENOTFOUND` - Provisioning is complete but no provisioned profile is available * `BADPARAM` - Buffer or size parameter is invalid **Syntax** ```cpp Status GetProvisionedProfile( char * out_profile, size_t * io_size ) ``` ## Implementation examples ## Certificate management functions ### GetCertificateManager() * **Description:** Retrieves the certificate manager for handling device certificates. Provides access to certificate operations and lifecycle management. * **Dependencies:** * Can optionally be called after Initialize() * **Parameters:** * `out_certificate_manager`: Output pointer to receive the certificate manager instance * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : * Certificate manager successfully retrieved * The pointer in `out_certificate_manager` is valid * **Error codes:** * `FAIL` : General failure. Check the log file for more information. * `BADPARAM` : `out_certificate_manager` is a null pointer and cannot be filled * `DENIED` : Guardian is not initialized * `MISCONFIGURED` : The loaded provisioned profile is not configured to allow certificate operations. * **Action:** * Use the retrieved certificate manager to import and export certificates. **Syntax** ```cpp Status GetCertificateManager( std::unique_ptr< CertificateManager > * out_certificate_manager ) ``` ### GetProvisionedRevocationList() * **Description:** * Retrieves the certificate revocation list (CRL) for checking certificate validity. * Used to identify revoked certificates that should no longer be trusted. * **Dependencies:** * Can optionally be called after successful provisioning (after GetProvisionedProfile()) * **Parameters:** * `out_ccrl`: Buffer to receive the certificate revocation list * Type: `char*` * `io_size`: Size of buffer on input, actual size on output * Provide size of buffer ( `out_ccrl` ) on input. After successful provisioning, `out_ccrl` sets to actual size of CRL. * Type: `size_t` * **Returns:** Status code indicating success or failure. * **Success code:** `OK` * `out_ccrl` has a valid revocation list of size `io_size` * **Error codes:** * `FAIL` - General failure. Check the log file for more information. * `INCOMPLETE` - Provisioning process did not complete, no revocation list available * `BADPARAM` : `out_ccrl` or `io_size` is null pointer, or `io_size` is 0 * `DENIED` - Online provisioning process is still running * `FILENOTFOUND` - Provisioning is complete but no revocation list is available * **Action:** Copies certificate revocation list to provided buffer **Syntax** ```cpp Status GetProvisionedRevocationList( char * out_ccrl, size_t * io_size ) ``` ## Security operations function ### FindSecureOperation() * **Description:** * Perform lookup for secure operation name. * Get secure operation handler for signing and verification operations. * **Dependencies:** * Can optionally be called after Initialize() * **Parameters:** * `in_secureop_name`: Secure operation name, terminated by null. * **Type**: `const char*` * `out_secureop`: Pointer to `unique_ptr` storage for located secure operation * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : The pointer in `out_secureop` is valid * **Error codes:** * `FAIL` : Could not find the operation specified by `in_secureop_name` * `BADPARAM` : `out_secureop` is null pointer and cannot be filled * `DENIED` : Guardian is not initialized * **Action:** * Sets `out_secureop` to the located operation * Will not modify `out_secureop` if the operation `in_secureop_name` is not located **Syntax** ```cpp Status FindSecureOperation( const char * in_secureop_name, std::unique_ptr< SecureOperation > * out_secureop ) ``` ## Service management functions ### FindService() * **Description:** * Performs lookup for service name to locate a configured service. * **Dependencies:** * Must be called after Initialize() * **Parameters:** * `in_service_name`: Service name, terminated by null * **Type:** `const char*` * `out_service`: Pointer to unique\_ptr storage for found service * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : The pointer in `out_service` is valid * **Error codes:** * `FAIL` : Could not find the service specified by `in_service_name` * `BADPARAM` : `out_service` is null pointer and cannot be filled * `DENIED` : Guardian is not initialized * **Action:** * Sets `out_service` to the located service * Will not modify `out_service` if the service in `in_service_name` is not located * or leaves unmodified if the service is not found **Syntax** ```cpp Status FindService( const char * in_service_name, std::unique_ptr< Service > * out_service ) ``` ### **CreateTask() - Service variant** * **Description:** * Create a task for service operations that separates the provided object and all children from Run. * Allows for threading of separate objects by removing them from the main Guardian Run loop. * **Dependencies:** * Must be called after Initialize() * Service object must be valid * **Parameters:** * `io_service`: Service component to place on a thread, will be consumed on success, unmodified on failure * `out_task`: Pointer to unique\_ptr storage for the task * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : out\_task has a valid task * **Error codes:** * `FAIL` : General failure. Check the log file for more information. * `BADPARAM` : io\_service or out\_task is null pointer * `DENIED` : Specified service is already in a task * **Action:** A component placed on a Task along with all children will not run when Guardian Run is called, allowing for threading of separate objects **Syntax** ```cpp Status CreateTask( std::unique_ptr< Service > * io_service, std::unique_ptr< Task > * out_task ) ``` ### CreateTask() - Session variant * **Description:** * Create a task for service operations that separates the provided object and all children from Run. * Allows for threading of separate objects by removing them from the main Run loop. * **Dependencies:** * Can optionally be called after Initialize() * Service object must be valid * **Parameters:** * `io_service`: Service component to place on a thread. This will be consumed on success, but not modified if not successful. * `out_task`: Pointer to `unique_ptr` storage for the task * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : `out_task` has a valid task * **Error codes:** * `FAIL` : General failure. Check the log file for more information. * `BADPARAM` : `io_service` or `out_task` is null pointer * `DENIED` : Specified service is already in a task * **Action:** * A component placed on a Task along with all children will not run when Run is called, allowing for threading of separate objects. * To return an object to the main `Run` loop, destroy the `unique_ptr`. **Syntax** ```cpp Status CreateTask( std::unique_ptr< Session > * io_session, std::unique_ptr< Task > * out_task ) ``` ### CreateTask() - ChannelGuard Variant * **Description:** * Create a task for channel operations that separates the provided object and all children from Run(). * Allows for threading of separate objects by removing them from the main Run() loop. * **Dependencies:** * Must be called after Initialize() * `ChannelGuard` object must be valid * **Parameters:** * `io_channelguard`: `ChannelGuard` component to place on a thread * `out_task`: Pointer to `unique_ptr` storage for the task * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : `out_task` has a valid task * **Error codes:** * `FAIL` : General failure. Check the log file for more information. * `BADPARAM` : `io_channelguard` or `out_task` is null pointer * `DENIED` : Specified `ChannelGuard` is already in a task and has not been returned * **Action:** * A component placed on a Task along with all children will not run when Run() is called, allowing for threading of separate objects. * To return an object to the main Run() loop, destroy the unique\_ptr. **Syntax** ```cpp Status CreateTask( std::unique_ptr< ChannelGuard > * io_channelguard, std::unique_ptr< Task > * out_task ) ``` ## **System management functions** ### GetAuthenticationManager() * **Description:** * Retrieve the running authentication manager. * Provides access to authentication operations and allow/deny lists for user-managed connections. * **Dependencies:** * Can optionally be called after Initialize() * **Parameters:** * `out_authentication_manager`: Pointer to `unique_ptr` storage for authentication manager * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : The pointer in `out_authentication_manager` is valid * **Error codes:** * `FAIL` : General failure. Check the log file for more information. * `BADPARAM` : `out_authentication_manager` is null pointer and cannot be filled * `DENIED` : Guardian is not initialized * `MISCONFIGURED` : The loaded profile is not configured to allow external authentication operations * **Action:** Use the retrieved authentication manager to get allow/deny lists for user managed connections **Syntax** ```cpp Status GetAuthenticationManager( std::unique_ptr< AuthenticationManager > * out_authentication_manager ) ``` ### GetTelemetryManager() * **Description:** * Retrieve the running telemetry manager. * Provides access to telemetry service interactions. * **Dependencies:** * Can optionally be called after Initialize() * **Parameters:** * `out_telemtry_manager`: Pointer to `unique_ptr` storage for telemetry manager * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : The pointer in `out_telemtry_manager` is valid * **Error codes:** * `FAIL` : General failure. Check the log file for more information. * `BADPARAM` : `out_telemtry_manager` is null pointer and cannot be filled * `DENIED` : Guardian is not initialized or there is no telemetry manager running * `MISCONFIGURED` : The loaded profile is not configured for telemetry * **Action:** Use the retrieved telemetry manager to interact with the telemetry service **Syntax** ```cpp Status GetTelemetryManager( std::unique_ptr< Telemetry > * out_telemtry_manager ) ``` ### \~Guardian() * **Description:** The destructor attempts a graceful shutdown of Guardian. * **Dependencies:** None - destructor is automatically called when object goes out of scope or is explicitly deleted * **Parameters:** None - destructor takes no parameters * **Returns:** Nothing since it is a destructor. * **Action:** The destructor will attempt to call Shutdown() for a graceful shutdown, then Guardian will destruct. **Syntax** ```cpp ~Guardian() ``` ### Shutdown() * **Description:** * Attempts to stop all internal state machines, shutting down Guardian. * Includes provisioning, telemetry, handshakes, authentication, services, sessions, and channels, INCLUDING those that have been placed or had a parent placed on another thread by [CreateTask](#createtask-service-variant). * **Dependencies:** * Can optionally be called after Initialize() * If there is data waiting to be sent it will return a failure code or require `in_force` * **Parameters:** * `in_force`: Drop all queued send data and shut down. Default value is `false`. * **Returns:** Status code indicating success or failure. * **Success code:** `OK` : Guardian is shut down successfully * **Error codes:** * `FAIL` : General failure. Check the log file for more information. * `AGAIN` : One or more transports has queued data to send * **Action:** Stops all internal state machines including provisioning, telemetry, handshakes, authentication, services, sessions, and channels. **Syntax** ```cpp Status Shutdown( const bool & in_force =false ) ``` The [medcrypt namespace ](/api-reference/api-reference/namespaces/namespacemedcrypt.md)contains the [guardian namespace](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian.md), which includes the following classes and structures. ## **Core classes** * [Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian.md) class: * **Description:** Root of Guardian system. * **Location:** medcrypt::guardian::Guardian * [AuthenticationManager](/api-reference/api-reference/classes/classmedcrypt-guardian-authenticationmanager.md) class: * **Description:** Container for authentication restrictions. * **Location:** medcrypt::guardian::AuthenticationManager * [ChannelGuard](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard.md) class: * **Description:** Name channel within a [Session](/api-reference/api-reference/classes/classmedcrypt-guardian-session.md). * **Location:** medcrypt::guardian::ChannelGuard * [SecureOperation](/api-reference/api-reference/classes/classmedcrypt-guardian-secureoperation.md) class: * **Description:** Named standalone operation. * **Location:** medcrypt::guardian::SecureOperation * [Service](/api-reference/api-reference/classes/classmedcrypt-guardian-service.md) class: * **Description:** Named group of connection and channel configurations. * **Location:** medcrypt::guardian::Service * [Session](/api-reference/api-reference/classes/classmedcrypt-guardian-session.md) class: * **Description:** Individual connection within a [Service](/api-reference/api-reference/classes/classmedcrypt-guardian-service.md). * **Location:** medcrypt::guardian::Session * [Task](/api-reference/api-reference/classes/classmedcrypt-guardian-task.md) class: * **Description:** Multithreading container. * **Location:** medcrypt::guardian::Task * [TransportInterface](/api-reference/api-reference/classes/classmedcrypt-guardian-transportinterface.md) class: * **Description:** [ConfigureTransport()](/api-reference/api-reference/classes/classmedcrypt-guardian-service.md#function-configuretransport) required interface. * **Location:** medcrypt::guardian::TransportInterface ## **Data structures** * [AuthenticationDomain](/api-reference/api-reference/classes/structmedcrypt-guardian-authenticationdomain.md) struct: * **Description:** Authentication restriction container. Restrictions for use by an authentication agent. * **Location:** medcrypt::guardian::AuthenticationDomain * [InitializeOptions](/api-reference/api-reference/classes/structmedcrypt-guardian-initializeoptions.md) struct: * **Description:** Options used by [Initialize()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian.md#step-2-run-initialize) during setup. * **Location:** medcrypt::guardian::InitializeOptions * [ProvisioningOptions](/api-reference/api-reference/classes/structmedcrypt-guardian-provisioningoptions.md) struct: * **Description:** Options used by [StartProvisioningOnline()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian.md#step-4-startprovisioningonline). * **Location:** medcrypt::guardian::ProvisioningOptions ### Utility namespace & structures The [guardian namespace](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian.md) also includes the [utilities](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities.md) namespace, which includes the following structures: * [InitializeFiles](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-initializefiles.md) struct: * **Description:** Storage for initialization files used by [Initialize()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian.md#step-2-run-initialize). * **Location:** medcrypt::guardian::utilities::InitializeFiles * [ProvisionFiles](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisionfiles.md) struct: * **Description:** Storage for generating provision request files in [GenerateProvisionRequest()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian.md#step-3-run-generateprovisionrequest). * **Location:** medcrypt::guardian::utilities::ProvisionFiles * [ProvisionOnlineFiles](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisiononlinefiles.md) struct: * **Description:** Storage for online provisioning files in [StartProvisioningOnline()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian.md#step-4-startprovisioningonline). * **Location:** medcrypt::guardian::utilities::ProvisionOnlineFiles ## **Other namespaces** * [AuthenticationAllowDenyEnum](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum.md) namespace: * **Description:** Determines whether a specified list is in an allow or deny list. * **Location:** medcrypt::guardian::AuthenticationAllowDenyEnum * [GuardianStatusEnum](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum.md) namespace: * **Description:** Status codes returned by Guardian functions. * **Location:** medcrypt::guardian::GuardianStatusEnum * [LogLevelEnum](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum.md) namespace: * **Description:** Log levels returned by Guardian functions. * **Location:** medcrypt::guardian::LogLevelEnum --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.medcrypt.com/api-reference/api-overview.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.