Defines C-Style ProtectionEngine functions. More...

#include <stdint.h>
#include "mip_cc/application_info_cc.h"
#include "mip_cc/auth_callback_cc.h"
#include "mip_cc/common_types_cc.h"
#include "mip_cc/consent_callback_cc.h"
#include "mip_cc/dictionary_cc.h"
#include "mip_cc/error_cc.h"
#include "mip_cc/mip_macros_cc.h"
#include "mip_cc/protection/delegation_license_cc.h"
#include "mip_cc/protection/license_info_cc.h"
#include "mip_cc/protection/protection_handler_cc.h"
#include "mip_cc/protection/template_descriptor_cc.h"
#include "mip_cc/result_cc.h"
#include "mip_cc/string_list_cc.h"

Include dependency graph for protection_engine_cc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef mip_cc_handle *	mip_cc_protection_engine

typedef mip_cc_handle *	mip_cc_protection_engine_settings

Functions
	MIP_CC_API (mip_cc_result) MIP_CC_ProtectionEngine_CreateProtectionHandlerForPublishing(const mip_cc_protection_engine engine
	Creates a protection handler for publishing new content.

	MIP_CC_API (void) MIP_CC_ReleaseProtectionEngine(mip_cc_protection_engine engine)
	Release resources associated with a protection engine.

	MIP_CC_DEPRECATED_API (mip_cc_result) MIP_CC_CreateProtectionEngineSettingsWithIdentity(const mip_cc_identity *identity
	Create a settings object used to create a brand new protection engine.

Variables
char const int64_t int64_t *	actualClientDataSize

char const int64_t int64_t *	actualIdSize

const void mip_cc_template_descriptor const int64_t int64_t *	actualTemplatesSize

bool	allowCloudServiceOnly

const mip_cc_auth_callback	authCallback

mip_cc_string_list *	capabilities

const char *	capability

const char *	clientData

char *	clientDataBuffer

char const int64_t	clientDataBufferSize

int64_t *	clientDataSize

const mip_cc_cloud	cloud

const char *	cloudEndpointBaseUrl

const mip_cc_protection_handler_publishing_settings const void *	context

const mip_cc_dictionary	customSettings

const void const char const char const char const char *	delegatedUserEmail

const mip_cc_delegation_license_settings const void mip_cc_delegation_licenses *	delegationLicenses

const void const char *	documentId

const char const char mip_cc_protection_engine_settings *	engineSettings

const mip_cc_protection_handler_publishing_settings const void mip_cc_protection_handler mip_cc_error *	errorInfo

const mip_cc_protection_handler_publishing_settings const void mip_cc_protection_handler *	handler

char *	idBuffer

char const int64_t	idBufferSize

const mip_cc_identity *	identity

int64_t *	idSize

const void const char const char *	labelId

const void const char const char const char const char mip_cc_license_info *	licenseInfo

const char const char *	locale

const void const char const char const char *	ownerEmail

const char bool *	removed

const void const char const char const char const char mip_cc_string_list *	rights

const char *	sessionId

const mip_cc_protection_handler_publishing_settings	settings

int int	templateBatchingSize

const void mip_cc_template_descriptor const int64_t	templateBufferSize

const void mip_cc_template_descriptor *	templateDescriptors

int	templateRefreshIntervalHours

const void int64_t *	templatesSize

const char *	underlyingApplicationId

Detailed Description

Defines C-Style ProtectionEngine functions.

Definition in file protection_engine_cc.h.

Typedef Documentation

◆ mip_cc_protection_engine

typedef mip_cc_handle* mip_cc_protection_engine

Definition at line 53 of file protection_engine_cc.h.

◆ mip_cc_protection_engine_settings

typedef mip_cc_handle* mip_cc_protection_engine_settings

Definition at line 54 of file protection_engine_cc.h.

Function Documentation

◆ MIP_CC_API() [1/2]

MIP_CC_API ( mip_cc_result ) const

Creates a protection handler for publishing new content.

Gets the set of supported capabilities being passed to RMS.

Remove a capability from the set of capabilities supported when calling RMS.

Add a capability to the set of capabilities supported when calling RMS.

Sets whether or not only cloud service is allowed.

Sets underlying application ID.

Sets base URL for all service requests.

Sets cloud which affects endpoint URLs for all service requests.

Sets the session ID that can be used to correlate logs and telemetry.

Configures custom settings, used for feature gating and testing.

Sets the client data that will be stored opaquely alongside this engine and persist across sessions.

Create a settings object used to load an existing protection engine by engine ID if it already exists, else create a new engine.

Create a settings object used to create a brand new protection engine.

Get the delegation and end-user licenses associated with a protection license.

Get client data associated with a protection engine.

Gets the size of client data associated with a protection engine.

Get list of rights granted to a user for a label ID.

Get collection of templates available to a user.

Gets the number of RMS templates associated with a protection engine.

Gets engine ID.

Gets size of buffer required to engine ID.

Creates a protection handler for consuming existing content.

Parameters

engine	Engine under which a handler will be created
settings	Protection handler settings
context	Client context that will be opaquely passed to HttpDelegate and AuthDelegate
handler	[Output] Newly-created protection handler instance
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

engine	Protection engine
idSize	[Output] Size of buffer to hold engine ID (in number of chars)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

engine	Protection engine
idBuffer	[Output] Buffer the id will be copied into.
idBufferSize	Size (in number of chars) of the idBuffer.
actualIdSize	[Output] Number of chars written to the buffer
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: If idBuffer is null or insufficient, MIP_RESULT_ERROR_INSUFFICIENT_BUFFER will be returned and actualIdSize will be set to the minimum required buffer size.

Parameters

engine	Protection engine
context	Client context that will be opaquely passed to HttpDelegate and AuthDelegate
templatesSize	[Output] Number of templates
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: This API may result in an independent HTTP operation. Consider using 'MIP_CC_ProtectionEngine_GetTemplates' directly with a pre-defined buffer to avoid unnecessary extra HTTP operations.

Parameters

engine	Protection engine
context	Client context that will be opaquely passed to HttpDelegate and AuthDelegate
mip_cc_template_descriptor	[Output] buffer to create template handlers.
templateBufferSize	Size (in number of items) of the templateBuffer.
actualTemplatesSize	[Output] Number of template IDs written to the buffer
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: If templateBuffer is null or insufficient, MIP_RESULT_ERROR_INSUFFICIENT_BUFFER will be returned and actualTemplateSize will be set to the minimum required buffer size. Each mip_cc_template_descriptor must be released by the caller by calling MIP_CC_ReleaseTemplateDescriptor().

Parameters

engine	Protection engine
context	Client context that will be opaquely passed to HttpDelegate and AuthDelegate
documentId	Document ID assigned to the document
labelId	Label ID applied to the document
ownerEmail	Owner of the document
delagedUserEmail	Email of user if the authenticating user/application is acting on behalf of another user, empty if none
rights	[Output] List of rights granted to a user, memory owned by caller
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: The 'rights' variable must be released by the caller by calling MIP_CC_ReleaseStringList

Parameters

engine	Protection engine
context	Client context that will be opaquely passed to the HttpDelegate and AuthDelegate
documentId	Document ID assigned to the document
labelId	Label ID applied to the document
ownerEmail	Owner of the document
delagedUserEmail	Email of the user if the authenticating user/application is acting on behalf of another user, empty if none
licenseInfo	[Output] LicenseInfo pertaining to a given label id. Memory owned by caller.
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: The returned 'licenseInfo' (mip_cc_license_info*) must be freed by calling MIP_CC_ReleaseLicenseInfo

Parameters

engine	Protection engine
clientDataSize	[Output] Size of client data (in number of chars)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

engine	Protection engine
clientDataBuffer	[Output] Buffer the client data will be copied into
clientDataBufferSize	Size (in number of chars) of clientDataBuffer.
actualClientDataSize	[Output] Number of chars written to the buffer
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: If clientDataBuffer is null or insufficient, MIP_RESULT_ERROR_INSUFFICIENT_BUFFER will be returned and actualClientDataSize will be set to the minimum required buffer size.

Parameters

engine	The mip_cc_protection_engine and associated identity to use when querying the licenses
settings	A collection of mip_cc_delegation_license_settings that determine which licenses to retrieve
context	(Optional) Optional context that is passed along to any listening HttpDelegate.
delegationLicenses	[Output] Returned collection of mip_cc_delegation_license objects.
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: To avoid memory leaks, delegationLicenses must be released using MIP_CC_ReleaseDelegationLicenses.

Parameters

identity	Identity that will be associated with ProtectionEngine
authCallback	Callback object to be used for authentication, implemented by client application
clientData	Customizable client data that is stored alongside the engine
locale	Locale in which text results will output
engineSettings	[Output] Newly-created settings instance
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

engineId	ID of existing cached engine
identity	(Optional) Identity that will be associated with ProtectionEngine
authCallback	Callback object to be used for authentication, implemented by client application
clientData	Customizable client data that is stored alongside the engine
locale	Locale in which text results will output
engineSettings	[Output] Newly-created settings instance
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: 'identity' will only be used for new engines. If an engine with the specified engine id already exists in the local cache, the identity from the cached engine will be used instead.

Parameters

settings	Engine settings
clientData	Client data
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

engineSettings	Engine settings
customSettings	Key/value pairs of custom settings
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

settings	Engine settings
sessionId	Session ID that represents the lifetime of a protection engine
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

settings	Engine settings
cloud	Cloud identifier (default = Unknown)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: If cloud is not specified, then it will be determined by DNS lookup of the engine's identity domain if possible, else fall back to global cloud.

Parameters

settings	Engine settings
cloudEndpointBaseUrl	Base URL (e.g. 'https://api.aadrm.com')
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: This value will only be read and must be set for Cloud = MIP_CLOUD_CUSTOM

Parameters

settings	Engine settings
underlyingApplicationId	Application ID (could be a Guid)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

settings	Engine settings
allowCloudServiceOnly	A boolean value indicating whether or not only cloud service is allowed
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

settings	Engine settings
templateRefreshIntervalHours	How long, in hours, a cached template will be valid to use. A value of 0 means templates should never be cached. This is the default.
templateBatchingSize	If doing offline publishing, how many temlates will be fetched at a single time. Max 25.
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

engineSettings	Engine settings
capability	The capability to add to indicate a supported feature to RMS
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

engineSettings	Engine settings
capability	The capability to remove from the supported features in RMS
removed	[Output] A boolean indiciating if the supplied capability was removed.
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Parameters

engineSettings	Engine settings
capabilities	[Output] Gets the list of capabilities being passed to RMS
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: The returned 'capabilities' (mip_cc_string_list*) must be freed by calling MIP_CC_ReleaseStringList.

◆ MIP_CC_API() [2/2]

MIP_CC_API ( void )

Release resources associated with a protection engine.

Release resources associated with a protection engine settings.

Parameters

engine	Protection engine to release
engineSettings	Protection engine settings to be released

◆ MIP_CC_DEPRECATED_API()

MIP_CC_DEPRECATED_API ( mip_cc_result ) const

Create a settings object used to create a brand new protection engine.

Sets label filter.

Create a settings object used to load an existing policy engine by engine ID if it already exists, else create a new engine.

Create a settings object used to load an existing protection engine by engine ID if it already exists, else create a new engine.

Deprecated: See the replacement MIP_CC_CreateProtectionEngineSettingsWithIdentityAndAuthCallback

Parameters

identity	Identity that will be associated with ProtectionEngine
clientData	Customizable client data that is stored alongside the engine
locale	Locale in which text results will output
engineSettings	[Output] Newly-created settings instance
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Deprecated: See the replacement MIP_CC_CreateProtectionEngineSettingsWithEngineIdAndAuthCallback

Parameters

engineId	ID of existing cached engine
identity	(Optional) Identity that will be associated with ProtectionEngine
clientData	Customizable client data that is stored alongside the engine
locale	Locale in which text results will output
engineSettings	[Output] Newly-created settings instance
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: 'identity' will only be used for new engines. If an engine with the specified engine id already exists in the local cache, the identity from the cached engine will be used instead.

Deprecated: See the replacement MIP_CC_CreatePolicyEngineSettingsWithEngineIdAndAuthCallback

Parameters

engineId	ID of existing cached engine
identity	(Optional) Identity that will be associated with PolicyEngine
clientData	Customizable client data that is stored alongside the engine
locale	Locale in which text results will output
loadSensitivityTypes	Whether or not sensitivity types data (for classification) should also be loaded
settings	[Output] Newly-created settings instance
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Note: 'loadSensitivityTypes' should be 'true' only if application expects to later call MIP_CC_PolicyEngine_GetSensitivityTypes. Otherwise, it should be false to avoid an unnecessary HTTP operation.; 'identity' will only be used for new engines. If an engine with the specified engine id already exists in the local cache, the identity from the cached engine will be used instead.

Deprecated: See the replacement MIP_CC_PolicyEngineSettings_ConfigureFunctionality

Parameters

settings	Engine settings
labelFilter	enum representing label filter, if not set default is hyok, doublekeyencryption
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns: Result code indicating success or failure

Variable Documentation

◆ actualClientDataSize

char const int64_t int64_t* actualClientDataSize

Definition at line 262 of file protection_engine_cc.h.

◆ actualIdSize

char const int64_t int64_t* actualIdSize

Definition at line 131 of file protection_engine_cc.h.

◆ actualTemplatesSize

const void mip_cc_template_descriptor const int64_t int64_t* actualTemplatesSize

Definition at line 174 of file protection_engine_cc.h.

◆ allowCloudServiceOnly

bool allowCloudServiceOnly

Definition at line 475 of file protection_engine_cc.h.

◆ authCallback

const mip_cc_identity const mip_cc_auth_callback authCallback

Definition at line 343 of file protection_engine_cc.h.

◆ capabilities

mip_cc_string_list* capabilities

Definition at line 540 of file protection_engine_cc.h.

◆ capability

const char * capability

Definition at line 507 of file protection_engine_cc.h.

◆ clientData

const char * clientData

Definition at line 299 of file protection_engine_cc.h.

◆ clientDataBuffer

char* clientDataBuffer

Definition at line 260 of file protection_engine_cc.h.

◆ clientDataBufferSize

char const int64_t clientDataBufferSize

Definition at line 261 of file protection_engine_cc.h.

◆ clientDataSize

int64_t* clientDataSize

Definition at line 241 of file protection_engine_cc.h.

◆ cloud

const mip_cc_cloud cloud

Definition at line 431 of file protection_engine_cc.h.

◆ cloudEndpointBaseUrl

const char* cloudEndpointBaseUrl

Definition at line 447 of file protection_engine_cc.h.

◆ context

const mip_cc_document_state const mip_cc_application_action_state const void * context

Definition at line 77 of file protection_engine_cc.h.

◆ customSettings

const mip_cc_dictionary customSettings

Definition at line 400 of file protection_engine_cc.h.

◆ delegatedUserEmail

const char * delegatedUserEmail

Definition at line 199 of file protection_engine_cc.h.

◆ delegationLicenses

const mip_cc_delegation_license_settings const void mip_cc_delegation_licenses* delegationLicenses

Definition at line 282 of file protection_engine_cc.h.

◆ documentId

const void const char * documentId

Definition at line 196 of file protection_engine_cc.h.

◆ engineSettings

const mip_cc_identity const mip_cc_auth_callback const char const char mip_cc_protection_engine_settings * engineSettings

Definition at line 301 of file protection_engine_cc.h.

◆ errorInfo

mip_cc_string_list mip_cc_error* errorInfo

Definition at line 79 of file protection_engine_cc.h.

◆ handler

const mip_cc_protection_handler_consumption_settings const void mip_cc_protection_handler * handler

Definition at line 78 of file protection_engine_cc.h.

◆ idBuffer

char* idBuffer

Definition at line 129 of file protection_engine_cc.h.

◆ idBufferSize

char const int64_t idBufferSize

Definition at line 130 of file protection_engine_cc.h.

◆ identity

const mip_cc_identity * identity

Definition at line 323 of file protection_engine_cc.h.

◆ idSize

int64_t* idSize

Definition at line 110 of file protection_engine_cc.h.

◆ labelId

const void const char const char * labelId

Definition at line 197 of file protection_engine_cc.h.

◆ licenseInfo

const void const char const char const char const char mip_cc_license_info* licenseInfo

Definition at line 227 of file protection_engine_cc.h.

◆ locale

const mip_cc_identity const mip_cc_auth_callback const char const char * locale

Definition at line 300 of file protection_engine_cc.h.

◆ ownerEmail

const void const char const char const char * ownerEmail

Definition at line 198 of file protection_engine_cc.h.

◆ removed

const char bool* removed

Definition at line 523 of file protection_engine_cc.h.

◆ rights

const void const char const char const char const char mip_cc_string_list* rights

Definition at line 200 of file protection_engine_cc.h.

◆ sessionId

const char* sessionId

Definition at line 414 of file protection_engine_cc.h.

◆ settings

const mip_cc_cache_storage_type const void mip_cc_policy_profile_settings * settings

Definition at line 76 of file protection_engine_cc.h.

◆ templateBatchingSize

int int templateBatchingSize

Definition at line 493 of file protection_engine_cc.h.

◆ templateBufferSize

const void mip_cc_template_descriptor const int64_t templateBufferSize

Definition at line 173 of file protection_engine_cc.h.

◆ templateDescriptors

const void mip_cc_template_descriptor* templateDescriptors

Definition at line 172 of file protection_engine_cc.h.

◆ templateRefreshIntervalHours

int templateRefreshIntervalHours

Definition at line 492 of file protection_engine_cc.h.

◆ templatesSize

const void int64_t* templatesSize

Definition at line 150 of file protection_engine_cc.h.

◆ underlyingApplicationId

const char* underlyingApplicationId

Definition at line 461 of file protection_engine_cc.h.

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ mip_cc_protection_engine

◆ mip_cc_protection_engine_settings

Function Documentation

◆ MIP_CC_API() [1/2]

◆ MIP_CC_API() [2/2]

◆ MIP_CC_DEPRECATED_API()

Variable Documentation

◆ actualClientDataSize

◆ actualIdSize

◆ actualTemplatesSize

◆ allowCloudServiceOnly

◆ authCallback

◆ capabilities

◆ capability

◆ clientData

◆ clientDataBuffer

◆ clientDataBufferSize

◆ clientDataSize

◆ cloud

◆ cloudEndpointBaseUrl

◆ context

◆ customSettings

◆ delegatedUserEmail

◆ delegationLicenses

◆ documentId

◆ engineSettings

◆ errorInfo

◆ handler

◆ idBuffer

◆ idBufferSize

◆ identity

◆ idSize

◆ labelId

◆ licenseInfo

◆ locale

◆ ownerEmail

◆ removed

◆ rights

◆ sessionId

◆ settings

◆ templateBatchingSize

◆ templateBufferSize

◆ templateDescriptors

◆ templateRefreshIntervalHours

◆ templatesSize

◆ underlyingApplicationId