Microsoft Information Protection SDK - File SDK engine concepts

The mip::FileEngine in the MIP File SDK provides an interface to all operations performed on behalf of a specified identity. Add one engine for each user that signs in to the application. The engine performs all operations in the context of that identity.

The FileEngine has two primary responsibilities: listing labels for an authenticated user and creating file handlers to perform file operations on behalf of the user.

  • mip::FileEngine
  • ListSensitivityLabels(): Gets the list of labels for the loaded engine.
  • CreateFileHandler(): Creates a mip::FileHandler for a specific file or stream.

Add a file engine

As covered in Profile and engine objects, an engine can have two states - CREATED or LOADED. If it's not one of those two states, it doesn't exist. To create and load a state, make a single call to FileProfile::LoadAsync. If the engine already exists in the cached state, it's LOADED. If it doesn't exist, it's CREATED and LOADED. CREATED implies that the application has all the information from the service needed to load the engine. LOADED implies that all data structures necessary to use the engine exist in memory.

Create file engine settings

Similar to a profile, the engine also requires a settings object, mip::FileEngine::Settings. This object stores the unique engine identifier, the mip::AuthDelegate implementation, customizable client data for debugging or telemetry, and, optionally, the locale.

Here we create a FileEngine::Settings object called engineSettings using the identity of the application user.

FileEngine::Settings engineSettings(
  mip::Identity(mUsername), // mip::Identity.
  authDelegateImpl,         // auth delegate object
  "",                       // Client data. Customizable by developer, stored with engine.
  "en-US",                  // Locale.
  false);                   // Load sensitive information types for driving classification.

When creating engineSettings in this manner, also explicitly set a unique engineId:

engineSettings.SetEngineId(engineId);

Using the username or email helps ensure that the same engine loads each time the user uses the service or application.

Also valid is providing a custom engine ID:

FileEngine::Settings engineSettings(
  "myEngineId",     // string
  authDelegateImpl, // auth delegate object
  "",               // Client data in string format. Customizable by developer, stored with engine.
  "en-US",          // Locale. Default is en-US
  false);           // Load sensitive information types for driving classification. Default is false.

As a best practice, use a first parameter, id, that connects the engine to the associated user. An email address, UPN, or Microsoft Entra object GUID helps ensure that the ID is unique and can load from local state without calling the service.

Add the file engine

To add the engine, return to the promise/future pattern used to load the profile. Rather than creating the promise for mip::FileProfile, create it by using mip::FileEngine.

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

  // Instantiate the AuthDelegate implementation.
  auto authDelegateImpl = std::make_shared<sample::auth::AuthDelegateImpl>(appInfo, userName, password);

  //Create the FileEngine::Settings object
  FileEngine::Settings engineSettings("UniqueID", authDelegateImpl, "");

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

  //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::FileEngine>
  auto engine = engineFuture.get();

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

List sensitivity labels

Using the added engine, you can list all sensitivity labels available to the authenticated user by calling engine->ListSensitivityLabels().

ListSensitivityLabels() fetches the list of labels and attributes of those labels for a specific user from the service. The result is stored in a vector of std::shared_ptr<mip::Label>.

For more information, see the mip::Label class reference.

ListSensitivityLabels()

std::vector<shared_ptr<mip::Label>> labels = engine->ListSensitivityLabels();

Or, simplified:

auto labels = engine->ListSensitivityLabels();

Printing the names shows that the application successfully pulled policy from the service and got the labels. To apply the label, you need the label identifier. The following code iterates through all labels and displays the name and the id for each parent and child label.

//Iterate through all labels in the vector
for (const auto& label : labels) {
  //Print label name and GUID
  cout << label->GetName() << " : " << label->GetId() << endl;

  //Print child label name and GUID
  for (const auto& child : label->GetChildren()) {
    cout << "->  " << child->GetName() <<  " : " << child->GetId() << endl;
  }
}

You can use the collection of mip::Label returned by GetSensitivityLabels() to display all labels available to the user and then, when selected, use the ID to apply labels to a file.

Next steps

Now that the profile is loaded, the engine is added, and labels are available, you can add a handler to begin to read, write, or remove labels from files. For more information, see File handlers in the MIP SDK.

  • Last updated on