Microsoft Information Protection (MIP) SDK for C++: Reference 1.15
Doxygen-generated documentation for MIP SDK written in C++
Loading...
Searching...
No Matches
file_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#ifndef API_MIP_FILE_FILE_PROFILE_H_
29#define API_MIP_FILE_FILE_PROFILE_H_
30
31#include <memory>
32#include <string>
33#include <vector>
34
35#include "mip/common_types.h"
36#include "mip/dns_redirection.h"
37#include "mip/error.h"
40#include "mip/http_delegate.h"
41#include "mip/logger_delegate.h"
42#include "mip/mip_context.h"
43#include "mip/mip_namespace.h"
45
46MIP_NAMESPACE_BEGIN
47
48/**
49 * @brief FileProfile class is the root class for using the Microsoft Information Protection operations.
50 *
51 * A typical application will only need one Profile.
52 */
54public:
55
56 /**
57 * @brief Observer interface for clients to get notifications for profile related events.
58 *
59 * @note All errors inherit from mip::Error.
60 * @note Client should not call the engine back on the thread that calls the observer.
61 */
62 class Observer {
63 public:
64 virtual ~Observer() {}
65
66 /**
67 * @brief Called when profile was loaded successfully.
68 */
69 virtual void OnLoadSuccess(
70 const std::shared_ptr<mip::FileProfile>& profile,
71 const std::shared_ptr<void>& context) { UNUSED(profile); UNUSED(context); }
72
73 /**
74 * @brief Called when loading a profile caused an error.
75 */
76 virtual void OnLoadFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) {
77 UNUSED(error); UNUSED(context); }
78
79 /**
80 * @brief Called when list of engines was generated successfully.
81 */
83 const std::vector<std::string>& engineIds,
84 const std::shared_ptr<void>& context) { UNUSED(engineIds); UNUSED(context); }
85
86 /**
87 * @brief Called when listing engines caused an error.
88 */
90 const std::exception_ptr& error,
91 const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
92
93 /**
94 * @brief Called when an engine was unloaded successfully.
95 */
96 virtual void OnUnloadEngineSuccess(const std::shared_ptr<void>& context) { UNUSED(context); }
97
98 /**
99 * @brief Called when unloading an engine caused an error.
100 */
102 const std::exception_ptr& error,
103 const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
104
105 /**
106 * @brief Called when a new engine was added successfully.
107 */
108 virtual void OnAddEngineSuccess(
109 const std::shared_ptr<mip::FileEngine>& engine,
110 const std::shared_ptr<void>& context) { UNUSED(engine); UNUSED(context); }
111
112 /**
113 * @brief Called when adding a new engine caused an error.
114 */
115 virtual void OnAddEngineFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) {
116 UNUSED(error); UNUSED(context); }
117
118 /**
119 * @brief Called when an engine was deleted successfully.
120 */
121 virtual void OnDeleteEngineSuccess(const std::shared_ptr<void>& context) { UNUSED(context); }
122
123 /**
124 * @brief Called when deleting an engine caused an error.
125 */
127 const std::exception_ptr& error,
128 const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
129
130 /**
131 * @brief Called when the policy has changed for the engine with the given ID.
132 */
133 virtual void OnPolicyChanged(const std::string& engineId) { UNUSED(engineId); }
134
135 /**
136 * @brief Called prior to engine creation to describe whether or not the policy 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 OnAddPolicyEngineStarting(bool requiresPolicyFetch) { UNUSED(requiresPolicyFetch); }
145
146 protected:
148 };
149
150 /**
151 * @brief Settings used by FileProfile during its creation and throughout its lifetime
152 */
153 class Settings {
154 public:
155 /**
156 * @brief FileProfile::Settings constructor
157 *
158 * @param mipContext Global context settings
159 * @param cacheStorageType Store any cached state in memory or on disk
160 * @param consentDelegate Delegate used to obtain user permission to access external resources
161 * @param observer Observer instance that will receive notifications of events related to FileProfile
162 */
164 const std::shared_ptr<MipContext>& mipContext,
165 CacheStorageType cacheStorageType,
166 std::shared_ptr<ConsentDelegate> consentDelegate,
167 std::shared_ptr<Observer> observer)
168 : mMipContext(mipContext),
169 mCacheStorageType(cacheStorageType),
170 mConsentDelegate(consentDelegate),
171 mObserver(observer),
172 mCanCacheLicenses(true),
173 mDnsRedirection(DnsRedirection::MDEDiscovery) {}
174
175 /** @cond DOXYGEN_HIDE */
176 ~Settings() {}
177 /** @endcond */
178
179 /**
180 * @brief Get whether caches are stored in memory or on disk
181 *
182 * @return storage type used
183 */
184 CacheStorageType GetCacheStorageType() const { return mCacheStorageType; }
185
186 /**
187 * @brief Gets the consent delegate used to request user consent connecting to services
188 *
189 * @return Consent delegate used for requesting user consent
190 */
191 std::shared_ptr<ConsentDelegate> GetConsentDelegate() const { return mConsentDelegate; }
192
193 /**
194 * @brief Gets the observer that receives notifications of events related to FileProfile
195 *
196 * @return Observer that receives notifications of events related to FileProfile
197 */
198 std::shared_ptr<Observer> GetObserver() const { return mObserver; }
199
200 /**
201 * @brief Get MIP context which represents shared state across all profiles
202 *
203 * @return MIP context
204 */
205 std::shared_ptr<MipContext> GetMipContext() const { return mMipContext; }
206
207 /**
208 * @brief Get the HTTP delegate (if any) provided by the application
209 *
210 * @return HTTP delegate to be used for HTTP operations
211 */
212 std::shared_ptr<HttpDelegate> GetHttpDelegate() const { return mHttpDelegate; }
213
214 /**
215 * @brief Override default HTTP stack with client's own
216 *
217 * @param httpDelegate HTTP callback interface implemented by client application
218 */
219 void SetHttpDelegate(const std::shared_ptr<HttpDelegate>& httpDelegate) { mHttpDelegate = httpDelegate; }
220
221 /**
222 * @brief Get the TaskDispatcher delegate (if any) provided by the application
223 *
224 * @return TaskDispatcher delegate to be used for executing asynchronous tasks
225 */
226 std::shared_ptr<TaskDispatcherDelegate> GetTaskDispatcherDelegate() const { return mTaskDispatcherDelegate; }
227
228 /**
229 * @brief Override default asynchonous task dispatching handling with client's own
230 *
231 * @param taskDispatcherDelegate Task dispatching callback interface implemented by client application
232 *
233 * @note tasks can reference profile objects preventing its destruction as a result
234 * taskdispatcher queues should not be shared.
235 */
236 void SetTaskDispatcherDelegate(const std::shared_ptr<TaskDispatcherDelegate>& taskDispatcherDelegate) {
237 mTaskDispatcherDelegate = taskDispatcherDelegate;
238 }
239
240 /**
241 * @brief Sets the session ID
242 *
243 * @param sessionId Session ID that will be used to correlate logs/telemetry
244 */
245 void SetSessionId(const std::string& sessionId) {
246 mSessionId = sessionId;
247 }
248
249 /**
250 * @brief Gets the session ID
251 *
252 * @return Session ID that will be used to correlate logs/telemetry
253 */
254 const std::string& GetSessionId() const {
255 return mSessionId;
256 }
257
258 /**
259 * @brief Configures whether or not end user licenses (EULs) will be cached locally
260 *
261 * @param canCacheLicenses Whether or not engine should cache a license when opening protected content
262 *
263 * @note If true, opening protected content will cache the associated license locally. If false, opening protected
264 * content will always perform HTTP operation to acquire the license from the RMS service.
265 */
266 void SetCanCacheLicenses(bool canCacheLicenses) {
267 mCanCacheLicenses = canCacheLicenses;
268 }
269
270 /**
271 * @brief Gets whether or not end user licenses (EULs) are cached locally
272 *
273 * @return License caching configuration
274 */
275 bool CanCacheLicenses() const {
276 return mCanCacheLicenses;
277 }
278
279#if !defined(SWIG) && !defined(SWIG_DIRECTORS)
280 /**
281 * @brief Get logger context that will be opaquely passed to the logger delegate for logs associated with the created profile
282 *
283 * @return The logger context
284 */
285 const std::shared_ptr<void>& GetLoggerContext() const { return mLoggerContext; }
286#endif
287 /**
288 * @brief Sets the logger context that will be opaquely passed to the logger delegate for logs associated with the created profile
289 *
290 * @param loggerContext The logger context
291 *
292 */
293 void SetLoggerContext(const std::shared_ptr<void>& loggerContext) {
294 mLoggerContext = loggerContext;
295 }
296
297 /**
298 * @brief Gets the dns redirect mode
299 *
300 * @return The redirect mode used
301 */
303 return mDnsRedirection;
304 }
305
306 /**
307 * @brief Sets the dns redirection mode that controls how redirection is handled during online operations
308 *
309 * @param dnsRedirection The redirection mode to use
310 */
311 void SetDnsRedirection(DnsRedirection dnsRedirection) {
312 mDnsRedirection = dnsRedirection;
313 }
314
315 private:
316 std::shared_ptr<MipContext> mMipContext;
317 std::string mPath;
318 CacheStorageType mCacheStorageType;
319 std::shared_ptr<ConsentDelegate> mConsentDelegate;
320 std::shared_ptr<Observer> mObserver;
321 std::string mSessionId;
322 std::shared_ptr<HttpDelegate> mHttpDelegate;
323 std::shared_ptr<TaskDispatcherDelegate> mTaskDispatcherDelegate;
324 bool mCanCacheLicenses;
325 std::shared_ptr<void> mLoggerContext;
326 DnsRedirection mDnsRedirection;
327 };
328
329 /**
330 * @brief Starts loading a profile based on the provided |settings|.
331 * @return Async control object.
332 *
333 * @note FileProfile::Observer will be called upon success or failure.
334 */
335 FILE_API static std::shared_ptr<AsyncControl> __CDECL LoadAsync(
336 const Settings& settings,
337 const std::shared_ptr<void>& context);
338
339 /**
340 * @brief Gets library version.
341 *
342 * @return Version string
343 */
344 FILE_API static const char* __CDECL GetVersion();
345
346 /** @cond DOXYGEN_HIDE */
347 virtual ~FileProfile() {}
348 /** @endcond */
349
350 /**
351 * @brief Returns the profile settings.
352 */
353 virtual const Settings& GetSettings() const = 0;
354
355 /**
356 * @brief Starts list engines operation.
357 * @return Async control object.
358 *
359 * @note FileProfile::Observer will be called upon success or failure.
360 */
361 virtual std::shared_ptr<AsyncControl> ListEnginesAsync(const std::shared_ptr<void>& context) = 0;
362
363 /**
364 * @brief Starts unloading the file engine with the given ID.
365 * @return Async control object.
366 *
367 * @note FileProfile::Observer will be called upon success or failure.
368 */
369 virtual std::shared_ptr<AsyncControl> UnloadEngineAsync(
370 const std::string& id,
371 const std::shared_ptr<void>& context) = 0;
372
373 /**
374 * @brief Starts adding a new file engine to the profile.
375 * @return Async control object.
376 *
377 * @note FileProfile::Observer will be called upon success or failure.
378 */
379 virtual std::shared_ptr<AsyncControl> AddEngineAsync(
380 const FileEngine::Settings& settings,
381 const std::shared_ptr<void>& context) = 0;
382
383 /**
384 * @brief Starts deleting the file engine with the given ID. All data for the given profile will be deleted.
385 * @return Async control object.
386 *
387 * @note FileProfile::Observer will be called upon success or failure.
388 */
389 virtual std::shared_ptr<AsyncControl> DeleteEngineAsync(
390 const std::string& id,
391 const std::shared_ptr<void>& context) = 0;
392
393 /**
394 * @brief Trigger an authentication callback for policy
395 *
396 * @param cloud Azure cloud
397 * @param authDelegate Authentication callback that will be invoked
398 *
399 * @note MIP will not cache or do anything else with the value returned by the auth delegate. This function is
400 * recommended for applications that aren't "logged in" until after MIP requests an auth token. It allows
401 * an application to fetch a token before MIP actually requires one.
402 */
403 virtual void AcquirePolicyAuthToken(Cloud cloud, const std::shared_ptr<AuthDelegate>& authDelegate) const = 0;
404
405protected:
406/** @cond DOXYGEN_HIDE */
407 FileProfile() {}
408 /** @endcond */
409};
410
411MIP_NAMESPACE_END
412
413#endif // API_MIP_FILE_FILE_PROFILE_H_
Observer interface for clients to get notifications for profile related events.
virtual void OnDeleteEngineSuccess(const std::shared_ptr< void > &context)
Called when an engine was deleted successfully.
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 OnLoadSuccess(const std::shared_ptr< mip::FileProfile > &profile, const std::shared_ptr< void > &context)
Called when profile was loaded successfully.
virtual void OnAddPolicyEngineStarting(bool requiresPolicyFetch)
Called prior to engine creation to describe whether or not the policy engine's policy data must be fe...
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 OnAddEngineSuccess(const std::shared_ptr< mip::FileEngine > &engine, const std::shared_ptr< void > &context)
Called when a new engine was added successfully.
virtual void OnUnloadEngineFailure(const std::exception_ptr &error, const std::shared_ptr< void > &context)
Called when unloading an engine caused an error.
virtual void OnListEnginesFailure(const std::exception_ptr &error, const std::shared_ptr< void > &context)
Called when listing engines caused an error.
virtual void OnLoadFailure(const std::exception_ptr &error, const std::shared_ptr< void > &context)
Called when loading a profile caused an error.
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.
virtual void OnPolicyChanged(const std::string &engineId)
Called when the policy has changed for the engine with the given ID.
Settings used by FileProfile during its creation and throughout its lifetime.
void SetCanCacheLicenses(bool canCacheLicenses)
Configures whether or not end user licenses (EULs) will be cached locally.
CacheStorageType GetCacheStorageType() const
Get whether caches are stored in memory or on disk.
void SetTaskDispatcherDelegate(const std::shared_ptr< TaskDispatcherDelegate > &taskDispatcherDelegate)
Override default asynchonous task dispatching handling with client's own.
std::shared_ptr< Observer > GetObserver() const
Gets the observer that receives notifications of events related to FileProfile.
void SetHttpDelegate(const std::shared_ptr< HttpDelegate > &httpDelegate)
Override default HTTP stack with client's own.
Settings(const std::shared_ptr< MipContext > &mipContext, CacheStorageType cacheStorageType, std::shared_ptr< ConsentDelegate > consentDelegate, std::shared_ptr< Observer > observer)
FileProfile::Settings constructor.
bool CanCacheLicenses() const
Gets whether or not end user licenses (EULs) are cached locally.
const std::string & GetSessionId() const
Gets the session ID.
std::shared_ptr< ConsentDelegate > GetConsentDelegate() const
Gets the consent delegate used to request user consent connecting to services.
DnsRedirection GetDnsRedirection() const
Gets the dns redirect mode.
void SetSessionId(const std::string &sessionId)
Sets the session ID.
std::shared_ptr< MipContext > GetMipContext() const
Get MIP context which represents shared state across all profiles.
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< HttpDelegate > GetHttpDelegate() const
Get the HTTP delegate (if any) provided by the application.
void SetDnsRedirection(DnsRedirection dnsRedirection)
Sets the dns redirection mode that controls how redirection is handled during online operations.
std::shared_ptr< TaskDispatcherDelegate > GetTaskDispatcherDelegate() const
Get the TaskDispatcher delegate (if any) provided by the application.
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 ...
FileProfile class is the root class for using the Microsoft Information Protection operations.
virtual std::shared_ptr< AsyncControl > ListEnginesAsync(const std::shared_ptr< void > &context)=0
Starts list engines operation.
virtual void AcquirePolicyAuthToken(Cloud cloud, const std::shared_ptr< AuthDelegate > &authDelegate) const =0
Trigger an authentication callback for policy.
static FILE_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 std::shared_ptr< AsyncControl > DeleteEngineAsync(const std::string &id, const std::shared_ptr< void > &context)=0
Starts deleting the file engine with the given ID.
virtual const Settings & GetSettings() const =0
Returns the profile settings.
virtual std::shared_ptr< AsyncControl > UnloadEngineAsync(const std::string &id, const std::shared_ptr< void > &context)=0
Starts unloading the file engine with the given ID.
virtual std::shared_ptr< AsyncControl > AddEngineAsync(const FileEngine::Settings &settings, const std::shared_ptr< void > &context)=0
Starts adding a new file engine to the profile.
static FILE_API const char *__CDECL GetVersion()
Gets library version.
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 types used to control dns redirection.
DnsRedirection
Storage type for the caches.
@ MDEDiscovery
MDE DNS.
A file containing the MIP SDK error types.
#define FILE_API
Definition file_export.h:47
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.
MIP namespace macros.
A file containing the TaskDispatcherDelegate interface to be used to override MIP async task executor...