# 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:**&#x20;
  * Retrieves the certificate revocation list (CRL) for checking certificate validity.&#x20;
  * 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`&#x20;
* **Returns:** Status code indicating success or failure.
  * **Success code:** `OK`&#x20;
    * &#x20;`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:**&#x20;
  * Perform lookup for secure operation name.&#x20;
  * 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:**&#x20;
  * 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:**&#x20;
  * Sets `out_service` to the located service&#x20;
  * 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:**&#x20;
  * 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:**&#x20;
  * 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&#x20;
* **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 ](https://docs.medcrypt.com/api-reference/api-reference/namespaces/namespacemedcrypt)contains the [guardian namespace](https://docs.medcrypt.com/api-reference/api-reference/namespaces/namespacemedcrypt-guardian), which includes the following classes and structures.

## **Core classes**

* [Guardian](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-guardian) class:&#x20;
  * **Description:** Root of Guardian system.&#x20;
  * **Location:** medcrypt::guardian::Guardian
* [AuthenticationManager](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-authenticationmanager) class:&#x20;
  * **Description:** Container for authentication restrictions.&#x20;
  * **Location:** medcrypt::guardian::AuthenticationManager
* [ChannelGuard](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard) class:&#x20;
  * **Description:** Name channel within a [Session](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-session).&#x20;
  * **Location:** medcrypt::guardian::ChannelGuard
* [SecureOperation](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-secureoperation) class:&#x20;
  * **Description:** Named standalone operation.&#x20;
  * **Location:** medcrypt::guardian::SecureOperation
* [Service](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-service) class:&#x20;
  * **Description:** Named group of connection and channel configurations.
  * **Location:** medcrypt::guardian::Service
* [Session](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-session) class:&#x20;
  * **Description:** Individual connection within a [Service](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-service).
  * **Location:** medcrypt::guardian::Session
* [Task](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-task) class:&#x20;
  * **Description:** Multithreading container.&#x20;
  * **Location:** medcrypt::guardian::Task
* [TransportInterface](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-transportinterface) class:&#x20;
  * **Description:** [ConfigureTransport()](https://docs.medcrypt.com/api-reference/classes/classmedcrypt-guardian-service#function-configuretransport) required interface.&#x20;
  * **Location:** medcrypt::guardian::TransportInterface

## **Data structures**

* [AuthenticationDomain](https://docs.medcrypt.com/api-reference/api-reference/classes/structmedcrypt-guardian-authenticationdomain) struct:&#x20;
  * **Description:** Authentication restriction container. Restrictions for use by an authentication agent.&#x20;
  * **Location:** medcrypt::guardian::AuthenticationDomain
* [InitializeOptions](https://docs.medcrypt.com/api-reference/api-reference/classes/structmedcrypt-guardian-initializeoptions) struct:&#x20;
  * **Description:** Options used by [Initialize()](https://docs.medcrypt.com/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize) during setup.&#x20;
  * **Location:** medcrypt::guardian::InitializeOptions
* [ProvisioningOptions](https://docs.medcrypt.com/api-reference/api-reference/classes/structmedcrypt-guardian-provisioningoptions) struct:&#x20;
  * **Description:** Options used by [StartProvisioningOnline()](https://docs.medcrypt.com/api-reference/classes/classmedcrypt-guardian-guardian#step-4-startprovisioningonline).&#x20;
  * **Location:** medcrypt::guardian::ProvisioningOptions

### Utility namespace & structures

The [guardian namespace](https://docs.medcrypt.com/api-reference/api-reference/namespaces/namespacemedcrypt-guardian) also includes the [utilities](https://docs.medcrypt.com/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities) namespace, which includes the following structures:

* [InitializeFiles](https://docs.medcrypt.com/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-initializefiles) struct:&#x20;
  * **Description:** Storage for initialization files used by [Initialize()](https://docs.medcrypt.com/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize).&#x20;
  * **Location:** medcrypt::guardian::utilities::InitializeFiles
* [ProvisionFiles](https://docs.medcrypt.com/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisionfiles) struct:&#x20;
  * **Description:** Storage for generating provision request files in [GenerateProvisionRequest()](https://docs.medcrypt.com/api-reference/classes/classmedcrypt-guardian-guardian#step-3-run-generateprovisionrequest).&#x20;
  * **Location:** medcrypt::guardian::utilities::ProvisionFiles
* [ProvisionOnlineFiles](https://docs.medcrypt.com/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisiononlinefiles) struct:
  * **Description:** Storage for online provisioning files in [StartProvisioningOnline()](https://docs.medcrypt.com/api-reference/classes/classmedcrypt-guardian-guardian#step-4-startprovisioningonline).
  * **Location:** medcrypt::guardian::utilities::ProvisionOnlineFiles

## **Other namespaces**

* [AuthenticationAllowDenyEnum](https://docs.medcrypt.com/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum)  namespace:&#x20;
  * **Description:** Determines whether a specified list is in an allow or deny list.
  * **Location:** medcrypt::guardian::AuthenticationAllowDenyEnum
* [GuardianStatusEnum](https://docs.medcrypt.com/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum) namespace:
  * **Description:** Status codes returned by Guardian functions.
  * **Location:** medcrypt::guardian::GuardianStatusEnum
* [LogLevelEnum](https://docs.medcrypt.com/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum) namespace:
  * **Description:** Log levels returned by Guardian functions.&#x20;
  * **Location:** medcrypt::guardian::LogLevelEnum