Microsoft Information Protection (MIP) SDK for C++: Reference 1.15
Doxygen-generated documentation for MIP SDK written in C++
Loading...
Searching...
No Matches
policy_profile.h
Go to the documentation of this file.
1/*
2 *
3 * Copyright (c) Microsoft Corporation.
4 * All rights reserved.
5 *
6 * This code is licensed under the MIT License.
7 *
8 * Permission is hereby granted, free of charge, to any person obtaining a copy
9 * of this software and associated documentation files(the "Software"), to deal
10 * in the Software without restriction, including without limitation the rights
11 * to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
12 * copies of the Software, and to permit persons to whom the Software is
13 * furnished to do so, subject to the following conditions :
14 *
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24 * THE SOFTWARE.
25 *
26 */
27/**
28 * @brief This file contains the PolicyProfile class which includes the PolicyProfile::Observer and the
29 * PolicyProfile::Settings classes.
30 *
31 * @file policy_profile.h
32 */
33
34#ifndef API_MIP_UPE_POLICY_PROFILE_H_
35#define API_MIP_UPE_POLICY_PROFILE_H_
36
37#include <memory>
38#include <string>
39#include <vector>
40
41#include "mip/common_types.h"
42#include "mip/error.h"
43#include "mip/http_delegate.h"
44#include "mip/logger_delegate.h"
45#include "mip/mip_context.h"
46#include "mip/mip_export.h"
47#include "mip/mip_namespace.h"
50
51MIP_NAMESPACE_BEGIN
52
53/**
54 * @brief PolicyProfile class is the root class for using the Microsoft Information Protection operations.
55 * A typical application will only need one PolicyProfile but it can create multiple profiles if needed.
56 */
58public:
59 /**
60 * @brief Observer interface for clients to get notifications for profile related events.
61 *
62 * @note All errors inherit from mip::Error.
63 * @note Client should not call the engine back on the thread that calls the observer.
64 */
65 class Observer {
66 public:
67
68 /**
69 * @brief Called when profile was loaded successfully.
70 *
71 * @param profile the current profile used to start the operation.
72 * @param context the context passed to the LoadAsync operation.
73 */
74 virtual void OnLoadSuccess(
75 const std::shared_ptr<PolicyProfile>& profile,
76 const std::shared_ptr<void>& context) { UNUSED(profile); UNUSED(context); }
77
78 /**
79 * @brief Called when loading a profile caused an error.
80 *
81 * @param error the error that caused the load operation to fail.
82 * @param context the context passed to the LoadAsync operation.
83 */
84 virtual void OnLoadFailure(
85 const std::exception_ptr& error,
86 const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
87
88 /**
89 * @brief Called when list of engines was generated successfully.
90 *
91 * @param engineIds a list of engine IDs the are available.
92 * @param context the context passed to the ListEnginesAsync operation.
93 */
95 const std::vector<std::string>& engineIds,
96 const std::shared_ptr<void>& context) { UNUSED(engineIds); UNUSED(context); }
97
98 /**
99 * @brief Called when listing engines caused an error.
100 *
101 * @param error the error that caused the list engine operation to fail.
102 * @param context the context passed to the ListEnginesAsync operation.
103 */
105 const std::exception_ptr& error,
106 const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
107
108 /**
109 * @brief Called when an engine was unloaded successfully.
110 *
111 * @param context the context passed to the UnloadEngineAsync operation.
112 */
113 virtual void OnUnloadEngineSuccess(const std::shared_ptr<void>& context) { UNUSED(context); }
114
115 /**
116 * @brief Called when unloading an engine caused an error.
117 *
118 * @param error the error that caused the unload engine operation to fail.
119 * @param context the context passed to the UnloadEngineAsync operation.
120 */
122 const std::exception_ptr& error,
123 const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
124
125 /**
126 * @brief Called when a new engine was added successfully.
127 *
128 * @param engine the newly-added engine
129 * @param context the context passed to the AddEngineAsync operation
130 */
131 virtual void OnAddEngineSuccess(
132 const std::shared_ptr<PolicyEngine>& engine,
133 const std::shared_ptr<void>& context) { UNUSED(engine); UNUSED(context); }
134
135 /**
136 * @brief Called prior to engine creation to describe whether or not the engine's policy data must be fetched from
137 * the server or whether it can be created from locally cached data.
138 *
139 * @param requiresPolicyFetch Describes whether engine data must be fetched via HTTP or if it will be loaded from cache
140 *
141 * @note This optional callback may be used by an application to be informed whether or not an AddEngineAsync
142 * operation will require an HTTP operation (with its associated delay) to complete.
143 */
144 virtual void OnAddEngineStarting(bool requiresPolicyFetch) { UNUSED(requiresPolicyFetch); }
145
146 /**
147 * @brief Called when adding a new engine caused an error.
148 *
149 * @param error the error that caused the add engine operation to fail.
150 * @param context the context passed to the AddEngineAsync operation.
151 */
152 virtual void OnAddEngineFailure(
153 const std::exception_ptr& error,
154 const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
155
156 /**
157 * @brief Called when an engine was deleted successfully.
158 *
159 * @param context the context passed to the DeleteEngineAsync operation.
160 */
161 virtual void OnDeleteEngineSuccess(const std::shared_ptr<void>& context) { UNUSED(context); }
162
163 /**
164 * @brief Called when deleting an engine caused an error.
165 *
166 * @param error the error that caused the delete engine operation to fail.
167 * @param context the context passed to the DeleteEngineAsync operation.
168 */
170 const std::exception_ptr& error,
171 const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
172
173 /**
174 * @brief Called when the policy has changed for the engine with the given ID, Or when the loaded Custom Sensitivity Types
175 * have changed.
176 *
177 * @param engineId the engine
178 * @note To load the new policy it is necessary to call AddEngineAsync again with the engine ID given.
179 */
180 virtual void OnPolicyChanged(const std::string& engineId) { UNUSED(engineId); }
181
182 /** @cond DOXYGEN_HIDE */
183 virtual ~Observer() { }
184 protected:
185 Observer() { }
186 /** @endcond */
187 };
188
189 /**
190 * @brief Settings used by PolicyProfile during its creation and throughout its lifetime
191 */
192 class Settings {
193 public:
194 /**
195 * @brief Interface for configuring the profile.
196 *
197 * @param mipContext Global context settings
198 * @param cacheStorageType Store any cached state in memory or on disk
199 * @param observer A class implementing the PolicyProfile::Observer interface. Can be nullptr.
200 */
202 const std::shared_ptr<MipContext>& mipContext,
203 CacheStorageType cacheStorageType,
204 const std::shared_ptr<PolicyProfile::Observer>& observer)
205 : mMipContext(mipContext),
206 mCacheStorageType(cacheStorageType),
207 mObserver(observer) {}
208
209 /**
210 * @brief Get whether caches are stored in memory or on disk
211 *
212 * @return storage type used
213 */
214 CacheStorageType GetCacheStorageType() const { return mCacheStorageType; }
215
216 /**
217 * @brief Get the event observer.
218 *
219 * @return the event observer.
220 */
221 const std::shared_ptr<PolicyProfile::Observer>& GetObserver() const { return mObserver; }
222
223 /**
224 * @brief Get MIP context which represents shared state across all profiles
225 *
226 * @return MIP context
227 */
228 std::shared_ptr<MipContext> GetMipContext() const { return mMipContext; }
229
230 /**
231 * @brief Get the HTTP delegate (if any) provided by the application
232 *
233 * @return Http delegate to be used for HTTP operations
234 */
235 std::shared_ptr<HttpDelegate> GetHttpDelegate() const { return mHttpDelegate; }
236
237 /**
238 * @brief Override default HTTP stack with client's own
239 *
240 * @param httpDelegate Http callback interface implemented by client application
241 */
242 void SetHttpDelegate(const std::shared_ptr<HttpDelegate>& httpDelegate) { mHttpDelegate = httpDelegate; }
243
244 /**
245 * @brief Get the #StorageDelegate (if any) provided by the application
246 *
247 * @return #StorageDelegate to be used for cache operations
248 */
249 std::shared_ptr<StorageDelegate> GetStorageDelegate() const { return mStorageDelegate; }
250
251 /**
252 * @brief Override default storage cache with client's own implementation.
253 *
254 * @param storageDelegate #StorageDelegate implemented by client application
255 */
256 void SetStorageDelegate(const std::shared_ptr<StorageDelegate>& storageDelegate) { mStorageDelegate = storageDelegate; }
257
258 /**
259 * @brief Get the TaskDispatcher delegate (if any) provided by the application
260 *
261 * @return TaskDispatcher delegate to be used for executing asynchronous tasks
262 */
263 std::shared_ptr<TaskDispatcherDelegate> GetTaskDispatcherDelegate() const { return mTaskDispatcherDelegate; }
264
265 /**
266 * @brief Override default asynchronous task dispatching handling with client's own
267 *
268 * @param taskDispatcherDelegate Task dispatching callback interface implemented by client application
269 *
270 * @note tasks can reference profile objects preventing its destruction as a result
271 * taskdispatcher queues should not be shared.
272 */
273 void SetTaskDispatcherDelegate(const std::shared_ptr<TaskDispatcherDelegate>& taskDispatcherDelegate) {
274 mTaskDispatcherDelegate = taskDispatcherDelegate;
275 }
276
277 void SetSessionId(const std::string& sessionId) {
278 mSessionId = sessionId;
279 }
280
281 const std::string& GetSessionId() const {
282 return mSessionId;
283 }
284
285 /**
286 * @brief Set the custom settings, used for feature gating and testing.
287 *
288 * @param customSettings List of name/value pairs.
289 */
290 void SetCustomSettings(const std::vector<std::pair<std::string, std::string>>& customSettings) {
291 mCustomSettings = customSettings;
292 }
293
294 /**
295 * @brief Get the custom settings, used for feature gating and testing.
296 *
297 * @return List of name/value pairs.
298 */
299 const std::vector<std::pair<std::string, std::string>>& GetCustomSettings() const {
300 return mCustomSettings;
301 }
302#if !defined(SWIG) && !defined(SWIG_DIRECTORS)
303 /**
304 * @brief Get logger context that will be opaquely passed to the logger delegate for logs associated with the created profile
305 *
306 * @return The logger context
307 */
308 const std::shared_ptr<void>& GetLoggerContext() const { return mLoggerContext; }
309#endif
310 /**
311 * @brief Sets the logger context that will be opaquely passed to the logger delegate for logs associated with the created profile
312 *
313 * @param loggerContext The logger context
314 *
315 */
316 void SetLoggerContext(const std::shared_ptr<void>& loggerContext) {
317 mLoggerContext = loggerContext;
318 }
319
320 /** @cond DOXYGEN_HIDE */
321 ~Settings() { }
322 private:
323 std::shared_ptr<MipContext> mMipContext;
324 CacheStorageType mCacheStorageType;
325 std::shared_ptr<PolicyProfile::Observer> mObserver;
326 std::shared_ptr<HttpDelegate> mHttpDelegate;
327 std::shared_ptr<TaskDispatcherDelegate> mTaskDispatcherDelegate;
328 std::string mSessionId;
329 std::vector<std::pair<std::string, std::string>> mCustomSettings;
330 std::shared_ptr<void> mLoggerContext;
331 std::shared_ptr<StorageDelegate> mStorageDelegate;
332 /** @endcond */
333 };
334
335 /**
336 * @brief Starts loading a profile based on the provided settings.
337 *
338 * @param settings the profile settings used to load the profile object.
339 * @param context a context parameter that will be passed into the observer functions.
340 * @note PolicyProfile::Observer will be called upon success or failure.
341 */
342 MIP_API static std::shared_ptr<AsyncControl> __CDECL LoadAsync(
343 const Settings& settings,
344 const std::shared_ptr<void>& context);
345
346 /**
347 * @brief Loading a profile based on the provided settings.
348 *
349 * @param settings Settings used by PolicyProfile during its initialization and throughout its lifetime
350 *
351 * @return Newly created profile
352 */
353 MIP_API static std::shared_ptr<PolicyProfile> __CDECL Load(const Settings& settings);
354
355 /**
356 * @brief Get the library version.
357 *
358 * @return a version string,
359 */
360 MIP_API static const char* __CDECL GetVersion();
361
362 /**
363 * @brief Get the settings set on the profile.
364 *
365 * @return settings set on the profile.
366 */
367 virtual const Settings& GetSettings() const = 0;
368
369 /**
370 * @brief Starts list engines operation.
371 *
372 * @param context a parameter that will be passed into the observer functions.
373 * @note PolicyProfile::Observer will be called upon success or failure.
374 */
375 virtual std::shared_ptr<AsyncControl> ListEnginesAsync(const std::shared_ptr<void>& context) = 0;
376
377 /**
378 * @brief List of engines.
379 *
380 * @return Cached engine IDs
381 */
382 virtual std::vector<std::string> ListEngines() = 0;
383
384 /**
385 * @brief Starts unloading the policy engine with the given ID.
386 *
387 * @param id the unique engine ID.
388 * @param context a parameter that will be forwarded opaquely to the observer functions.
389 * @note PolicyProfile::Observer will be called upon success or failure.
390 */
391 virtual std::shared_ptr<AsyncControl> UnloadEngineAsync(
392 const std::string& id,
393 const std::shared_ptr<void>& context) = 0;
394
395 /**
396 * @brief Starts unloading the policy engine with the given ID.
397 *
398 * @param id the unique engine ID.
399 */
400 virtual void UnloadEngine(const std::string& id) = 0;
401
402 /**
403 * @brief Starts adding a new policy engine to the profile.
404 *
405 * @param settings the mip::PolicyEngine::Settings object that specifies the engine's settings.
406 * @param context a parameter that will be forwarded opaquely to the observer functions and optional HttpDelegate.
407 * @note PolicyProfile::Observer will be called upon success or failure.
408 */
409 virtual std::shared_ptr<AsyncControl> AddEngineAsync(
410 const PolicyEngine::Settings& settings,
411 const std::shared_ptr<void>& context) = 0;
412
413 /**
414 * @brief Add a new policy engine to the profile.
415 *
416 * @param settings the mip::PolicyEngine::Settings object that specifies the engine's settings.
417 * @param context a parameter that will be forwarded opaquely to the optional HttpDelegate
418 *
419 * @return Newly created PolicyEngine
420 */
421 virtual std::shared_ptr<PolicyEngine> AddEngine(
422 const PolicyEngine::Settings& settings,
423 const std::shared_ptr<void>& context) = 0;
424
425 /**
426 * @brief Starts deleting the policy engine with the given ID. All data for the given profile will be deleted.
427 *
428 * @param id the unique engine ID.
429 * @param context a parameter that will be passed into the observer functions.
430 * @note PolicyProfile::Observer will be called upon success or failure.
431 */
432 virtual std::shared_ptr<AsyncControl> DeleteEngineAsync(
433 const std::string& id,
434 const std::shared_ptr<void>& context) = 0;
435
436 /**
437 * @brief Delete the policy engine with the given ID. All data for the given engine will be deleted.
438 *
439 * @param id the unique engine ID.
440 */
441 virtual void DeleteEngine(const std::string& engineId) = 0;
442
443 /**
444 * @brief Trigger an authentication callback
445 *
446 * @param cloud Azure cloud
447 * @param authDelegate Authentication callback that will be invoked
448 *
449 * @note MIP will not cache or do anything else with the value returned by the auth delegate. This function is
450 * recommended for applications that aren't "logged in" until after MIP requests an auth token. It allows
451 * an application to fetch a token before MIP actually requires one.
452 */
453 virtual void AcquireAuthToken(Cloud cloud, const std::shared_ptr<AuthDelegate>& authDelegate) const = 0;
454
455 /** @cond DOXYGEN_HIDE */
456
457 virtual ~PolicyProfile() { }
458protected:
459 PolicyProfile() { }
460
461 /** @endcond */
462};
463
464MIP_NAMESPACE_END
465
466#endif // API_MIP_UPE_POLICY_PROFILE_H_
Defines the settings associated with a PolicyEngine.
Observer interface for clients to get notifications for profile related events.
virtual void OnPolicyChanged(const std::string &engineId)
Called when the policy has changed for the engine with the given ID, Or when the loaded Custom Sensit...
virtual void OnListEnginesSuccess(const std::vector< std::string > &engineIds, const std::shared_ptr< void > &context)
Called when list of engines was generated successfully.
virtual void OnDeleteEngineSuccess(const std::shared_ptr< void > &context)
Called when an engine was deleted successfully.
virtual void OnLoadFailure(const std::exception_ptr &error, const std::shared_ptr< void > &context)
Called when loading a profile caused an error.
virtual void OnAddEngineFailure(const std::exception_ptr &error, const std::shared_ptr< void > &context)
Called when adding a new engine caused an error.
virtual void OnAddEngineStarting(bool requiresPolicyFetch)
Called prior to engine creation to describe whether or not the engine's policy data must be fetched f...
virtual void OnUnloadEngineFailure(const std::exception_ptr &error, const std::shared_ptr< void > &context)
Called when unloading an engine caused an error.
virtual void OnAddEngineSuccess(const std::shared_ptr< PolicyEngine > &engine, const std::shared_ptr< void > &context)
Called when a new engine was added successfully.
virtual void OnListEnginesFailure(const std::exception_ptr &error, const std::shared_ptr< void > &context)
Called when listing engines caused an error.
virtual void OnLoadSuccess(const std::shared_ptr< PolicyProfile > &profile, const std::shared_ptr< void > &context)
Called when profile was loaded successfully.
virtual void OnDeleteEngineFailure(const std::exception_ptr &error, const std::shared_ptr< void > &context)
Called when deleting an engine caused an error.
virtual void OnUnloadEngineSuccess(const std::shared_ptr< void > &context)
Called when an engine was unloaded successfully.
Settings used by PolicyProfile during its creation and throughout its lifetime.
void SetSessionId(const std::string &sessionId)
Settings(const std::shared_ptr< MipContext > &mipContext, CacheStorageType cacheStorageType, const std::shared_ptr< PolicyProfile::Observer > &observer)
Interface for configuring the profile.
void SetLoggerContext(const std::shared_ptr< void > &loggerContext)
Sets the logger context that will be opaquely passed to the logger delegate for logs associated with ...
const std::shared_ptr< void > & GetLoggerContext() const
Get logger context that will be opaquely passed to the logger delegate for logs associated with the c...
std::shared_ptr< StorageDelegate > GetStorageDelegate() const
Get the StorageDelegate (if any) provided by the application.
CacheStorageType GetCacheStorageType() const
Get whether caches are stored in memory or on disk.
const std::string & GetSessionId() const
void SetTaskDispatcherDelegate(const std::shared_ptr< TaskDispatcherDelegate > &taskDispatcherDelegate)
Override default asynchronous task dispatching handling with client's own.
void SetHttpDelegate(const std::shared_ptr< HttpDelegate > &httpDelegate)
Override default HTTP stack with client's own.
void SetStorageDelegate(const std::shared_ptr< StorageDelegate > &storageDelegate)
Override default storage cache with client's own implementation.
void SetCustomSettings(const std::vector< std::pair< std::string, std::string > > &customSettings)
Set the custom settings, used for feature gating and testing.
const std::shared_ptr< PolicyProfile::Observer > & GetObserver() const
Get the event observer.
std::shared_ptr< TaskDispatcherDelegate > GetTaskDispatcherDelegate() const
Get the TaskDispatcher delegate (if any) provided by the application.
const std::vector< std::pair< std::string, std::string > > & GetCustomSettings() const
Get the custom settings, used for feature gating and testing.
std::shared_ptr< MipContext > GetMipContext() const
Get MIP context which represents shared state across all profiles.
std::shared_ptr< HttpDelegate > GetHttpDelegate() const
Get the HTTP delegate (if any) provided by the application.
PolicyProfile class is the root class for using the Microsoft Information Protection operations.
virtual std::vector< std::string > ListEngines()=0
List of engines.
virtual std::shared_ptr< AsyncControl > AddEngineAsync(const PolicyEngine::Settings &settings, const std::shared_ptr< void > &context)=0
Starts adding a new policy engine to the profile.
virtual void DeleteEngine(const std::string &engineId)=0
Delete the policy engine with the given ID.
virtual std::shared_ptr< AsyncControl > DeleteEngineAsync(const std::string &id, const std::shared_ptr< void > &context)=0
Starts deleting the policy engine with the given ID.
virtual std::shared_ptr< PolicyEngine > AddEngine(const PolicyEngine::Settings &settings, const std::shared_ptr< void > &context)=0
Add a new policy engine to the profile.
virtual std::shared_ptr< AsyncControl > UnloadEngineAsync(const std::string &id, const std::shared_ptr< void > &context)=0
Starts unloading the policy engine with the given ID.
static MIP_API std::shared_ptr< PolicyProfile > __CDECL Load(const Settings &settings)
Loading a profile based on the provided settings.
static MIP_API const char *__CDECL GetVersion()
Get the library version.
virtual const Settings & GetSettings() const =0
Get the settings set on the profile.
virtual std::shared_ptr< AsyncControl > ListEnginesAsync(const std::shared_ptr< void > &context)=0
Starts list engines operation.
static MIP_API std::shared_ptr< AsyncControl > __CDECL LoadAsync(const Settings &settings, const std::shared_ptr< void > &context)
Starts loading a profile based on the provided settings.
virtual void UnloadEngine(const std::string &id)=0
Starts unloading the policy engine with the given ID.
virtual void AcquireAuthToken(Cloud cloud, const std::shared_ptr< AuthDelegate > &authDelegate) const =0
Trigger an authentication callback.
A file Containing the common types used by the upe, file and protection modules.
Cloud
Azure cloud identifier.
CacheStorageType
Storage type for the caches.
A file containing the MIP SDK error types.
Contains HttpDelegate interface definition used to override MIP HTTP stack.
A file containing the LoggerDelegate class to be used to override MIP logger.
File containing definition of MipContext.
A file export/import macros.
MIP namespace macros.
This file contains the PolicyEngine class which includes the PolicyEngine::Settings class.
A file containing the TaskDispatcherDelegate interface to be used to override MIP async task executor...