Microsoft Information Protection SDK - Protection SDK engine concepts

Implementation: Add a protection engine

In the File SDK, the mip::ProtectionProfile class is the root class for all SDK operations. After you create the profile, you can add an engine to the profile.

The following example demonstrates how to use a single engine for a single authenticated user.

Implementation: Create protection engine settings

Similar to a profile, the engine also requires a settings object, mip::ProtectionEngine::Settings. This object stores the unique engine identifier, the mip::AuthDelegate used to acquire tokens, customizable client data that you can use for debugging or telemetry, and, optionally, the locale.

The following code creates a ProtectionEngine::Settings object called engineSettings.

ProtectionEngine::Settings engineSettings("UniqueID", authDelegate, "");

Note

If you create the protection settings object with this method, also set the identity on the ProtectionEngine::Settings object by using SetIdentity() or the target cloud environment by using SetCloud().

As a best practice, use the first parameter, id, to identify the associated user, or use a mip::Identity object. To initialize the settings with mip::Identity:

ProtectionEngine::Settings engineSettings(mip::Identity("Bob@Contoso.com"), authDelegate, "");

When you create engineSettings this way, also explicitly set a unique engineId by using:

engineSettings.SetEngineId(engineId);

Use the username or email to help ensure that the engine loads consistently each time the user uses the service or application.

Implementation: Add the protection engine

Use the future/promise pattern used to load the profile to add the engine. Instead of creating the promise for mip::ProtectionProfile, use mip::ProtectionEngine.


  //auto profile will be std::shared_ptr<mip::ProtectionProfile>
  auto profile = profileFuture.get();

  //Create the ProtectionEngine::Settings object
  ProtectionEngine::Settings engineSettings("UniqueID", authDelegate, "");

  //Create a promise for std::shared_ptr<mip::ProtectionEngine>
  auto enginePromise = std::make_shared<std::promise<std::shared_ptr<mip::ProtectionEngine>>>();

  //Instantiate the future from the promise
  auto engineFuture = enginePromise->get_future();

  //Add the engine using AddEngineAsync, passing in the engine settings and the promise
  profile->AddEngineAsync(engineSettings, enginePromise);

  //get the future value and store in std::shared_ptr<mip::ProtectionEngine>
  auto engine = engineFuture.get();

The code adds an engine for the authenticated user to the profile.

Implementation: List templates

After you add the engine, you can list all of the sensitivity templates available to the authenticated user by calling engine->GetTemplatesAsync().

GetTemplatesAsync() fetches the list of template descriptors. The method stores the result in a vector of std::shared_ptr<mip::TemplateDescriptor>.

Implementation: ListSensitivityTemplates()

auto loadPromise = std::make_shared<std::promise<std::vector<std::shared_ptr<mip::TemplateDescriptor>>>>();
auto loadFuture = loadPromise->get_future();
engine->GetTemplatesAsync(engineObserver, loadPromise);
auto templates = loadFuture.get();

Implementation: Print the template IDs

//Iterate through all template IDs in the vector
for (const auto& temp : templates) {
  cout << "Template:" << "\n\tId: " << temp->GetId() << endl;
}

Printing the names shows that the application successfully pulled policy from the service and retrieved the templates. To apply the template, you need the template identifier.

You can map templates to labels only through Policy SDK by examining the result of ComputeActions().

Next steps

Now that you loaded the profile, added the engine, and have templates, you can add a handler to begin to read, write, or remove templates from files. See Protection handler concepts.

  • Last updated on