protection_engine_cc.h File Reference

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"

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 (void) MIP_CC_ReleaseProtectionEngine(mip_cc_protection_engine engine)
	Release resources associated with a protection engine.
	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_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
const mip_cc_protection_handler_publishing_settings	settings
const mip_cc_protection_handler_publishing_settings const void *	context
const mip_cc_protection_handler_publishing_settings const void mip_cc_protection_handler *	handler
const mip_cc_protection_handler_publishing_settings const void mip_cc_protection_handler mip_cc_error *	errorInfo
int64_t *	idSize
char *	idBuffer
char const int64_t	idBufferSize
char const int64_t int64_t *	actualIdSize
const void int64_t *	templatesSize
const void mip_cc_template_descriptor *	templateDescriptors
const void mip_cc_template_descriptor const int64_t	templateBufferSize
const void mip_cc_template_descriptor const int64_t int64_t *	actualTemplatesSize
const void const char *	documentId
const void const char const char *	labelId
const void const char const char const char *	ownerEmail
const void const char const char const char const char *	delegatedUserEmail
const void const char const char const char const char mip_cc_string_list *	rights
const void const char const char const char const char mip_cc_license_info *	licenseInfo
int64_t *	clientDataSize
char *	clientDataBuffer
char const int64_t	clientDataBufferSize
char const int64_t int64_t *	actualClientDataSize
const mip_cc_delegation_license_settings const void mip_cc_delegation_licenses *	delegationLicenses
const char *	clientData
const char const char *	locale
const char const char mip_cc_protection_engine_settings *	engineSettings
const mip_cc_identity *	identity
const mip_cc_auth_callback	authCallback
const mip_cc_dictionary	customSettings
const char *	sessionId
const mip_cc_cloud	cloud
const char *	cloudEndpointBaseUrl
const char *	underlyingApplicationId
bool	allowCloudServiceOnly
int	templateRefreshIntervalHours
int int	templateBatchingSize
const char *	capability
const char bool *	removed
mip_cc_string_list *	capabilities

Detailed Description

Defines C-Style ProtectionEngine functions.

Typedef Documentation

mip_cc_protection_engine

typedef mip_cc_handle* mip_cc_protection_engine

mip_cc_protection_engine_settings

typedef mip_cc_handle* mip_cc_protection_engine_settings

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

actualIdSize

char const int64_t int64_t* actualIdSize

actualTemplatesSize

const void mip_cc_template_descriptor const int64_t int64_t* actualTemplatesSize

allowCloudServiceOnly

bool allowCloudServiceOnly

authCallback

const mip_cc_identity const mip_cc_auth_callback authCallback

capabilities

mip_cc_string_list* capabilities

capability

const char * capability

clientData

const char * clientData

clientDataBuffer

char* clientDataBuffer

clientDataBufferSize

char const int64_t clientDataBufferSize

clientDataSize

int64_t* clientDataSize

cloud

const mip_cc_cloud cloud

cloudEndpointBaseUrl

const char* cloudEndpointBaseUrl

context

const mip_cc_delegation_license_settings const void* context

customSettings

const mip_cc_dictionary customSettings

delegatedUserEmail

const char * delegatedUserEmail

delegationLicenses

const mip_cc_delegation_license_settings const void mip_cc_delegation_licenses* delegationLicenses

documentId

const void const char * documentId

engineSettings

const mip_cc_identity const mip_cc_auth_callback const char const char mip_cc_protection_engine_settings * engineSettings

errorInfo

mip_cc_string_list mip_cc_error* errorInfo

handler

const mip_cc_protection_handler_consumption_settings const void mip_cc_protection_handler * handler

idBuffer

char* idBuffer

idBufferSize

char const int64_t idBufferSize

identity

const mip_cc_identity * identity

idSize

int64_t* idSize

labelId

const void const char const char * labelId

licenseInfo

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

locale

const mip_cc_identity const mip_cc_auth_callback const char const char * locale

ownerEmail

const void const char const char const char * ownerEmail

removed

const char bool* removed

rights

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

sessionId

const char* sessionId

settings

const mip_cc_cache_storage_type const void mip_cc_policy_profile_settings * settings

templateBatchingSize

int int templateBatchingSize

templateBufferSize

const void mip_cc_template_descriptor const int64_t templateBufferSize

templateDescriptors

const void mip_cc_template_descriptor* templateDescriptors

templateRefreshIntervalHours

int templateRefreshIntervalHours

templatesSize

const void int64_t* templatesSize

underlyingApplicationId

const char* underlyingApplicationId