Quickstart: Client application initialization for Protection SDKs (C++)

Article
01/30/2024

This quickstart shows you how to implement the client initialization pattern, used by the MIP C++ SDK at runtime.

Note

The steps outlined in this quickstart are required for any client application that uses the MIP Protection SDKs. These Quickstarts should be done serially after Application Initialization and implementation of Authentication delegate and Consent delegate classes.

Prerequisites

If you haven't already, be sure to:

Complete the steps in Microsoft Information Protection (MIP) SDK setup and configuration. This "Client application initialization" Quickstart relies on proper SDK setup and configuration.
Optionally:
- Review Profile and engine objects. The profile and engine objects are universal concepts, required by clients that use the MIP File/Policy/Protection SDKs.
- Review Authentication concepts to learn how authentication and consent are implemented by the SDK and the client application.
- Review Observer concepts to learn more about observers, and how they're implemented. The MIP SDK uses the observer pattern to implement asynchronous event notifications.

Create a Visual Studio solution and project

First we create and configure the initial Visual Studio solution and project, upon which the other Quickstarts build.

Open Visual Studio 2017, select the File menu, New, Project. In the New Project dialog:
- In the left pane, under Installed, Other Languages, select Visual C++.
- In the center pane, select Windows Console Application
- In the bottom pane, update the project Name, Location, and the containing Solution name accordingly.
- When finished, click the OK button in the lower right.
Add the Nuget package for the MIP Protection SDK to your project:
- In the Solution Explorer, right-click the project node (directly under the top/solution node), and select Manage NuGet packages...:
- When the NuGet Package Manager tab opens in the Editor Group tabs area:
  - Select Browse.
  - Enter "Microsoft.InformationProtection" in the search box.
  - Select the "Microsoft.InformationProtection.Protection" package.
  - Click "Install", then click "OK" when the Preview changes confirmation dialog displays.

Implement observer classes to monitor the Protection profile and engine objects

Now create a basic implementation for a Protection profile observer class, by extending the SDK's mip::ProtectionProfile::Observer class. The observer is instantiated and used later, to monitor the loading of the Protection profile object, and adding the engine object to the profile.

Add a new class to your project, which generates both the header/.h and implementation/.cpp files for you:
- In the Solution Explorer, right-click the project node again, select Add, then select Class.
- On the Add Class dialog:
  - In the Class Name field, enter "profile_observer". Notice that both the .h file and .cpp file fields are automatically populated, based on the name you enter.
  - When finished, click the OK button.

After generating the .h and .cpp files for the class, both files are opened in Editor Group tabs. Now update each file to implement your new observer class:

Update "profile_observer.h", by selecting/deleting the generated profile_observer class. Don't remove the preprocessor directives generated by the previous step (#pragma, #include). Then copy/paste the following source into the file, after any existing preprocessor directives:

#include <memory>
#include "mip/protection/protection_profile.h"
using std::exception_ptr;
using std::shared_ptr;


class ProtectionProfileObserver final : public mip::ProtectionProfile::Observer {
public:
     ProtectionProfileObserver() { }
     void OnLoadSuccess(const std::shared_ptr<mip::ProtectionProfile>& profile, const std::shared_ptr<void>& context) override;
     void OnLoadFailure(const std::exception_ptr& Failure, const std::shared_ptr<void>& context) override;
     void OnAddEngineSuccess(const std::shared_ptr<mip::ProtectionEngine>& engine, const std::shared_ptr<void>& context) override;
     void OnAddEngineFailure(const std::exception_ptr& Failure, const std::shared_ptr<void>& context) override;
};

Update "profile_observer.cpp", by selecting/deleting the generated profile_observer class implementation. Don't remove the preprocessor directives generated by the previous step (#pragma, #include). Then copy/paste the following source into the file, after any existing preprocessor directives:

#include <future>

using std::promise;
using std::shared_ptr;
using std::static_pointer_cast;
using mip::ProtectionEngine;
using mip::ProtectionProfile;

void ProtectionProfileObserver::OnLoadSuccess(const shared_ptr<ProtectionProfile>& profile, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<ProtectionProfile>>>(context);
     promise->set_value(profile);
}

void ProtectionProfileObserver::OnLoadFailure(const std::exception_ptr& error, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<ProtectionProfile>>>(context);
     promise->set_exception(error);
}

void ProtectionProfileObserver::OnAddEngineSuccess(const shared_ptr<ProtectionEngine>& engine, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<ProtectionEngine>>>(context);
     promise->set_value(engine);
}

void ProtectionProfileObserver::OnAddEngineFailure(const std::exception_ptr& error, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<ProtectionEngine>>>(context);
     promise->set_exception(error);
}

Following steps in 1. add a new class for Protection engine observer - "engine_observer" to your project, which generates both the header/.h and implementation/.cpp files for you.

After generating the .h and .cpp files for the class, both files are opened in Editor Group tabs. Now update each file to implement your new observer class:

Update "engine_observer.h", by selecting/deleting the generated engine_observer class. Don't remove the preprocessor directives generated by the previous step (#pragma, #include). Then copy/paste the following source into the file, after any existing preprocessor directives:

#include <memory>
#include "mip/protection/protection_engine.h"
using std::vector;
using std::exception_ptr;
using std::shared_ptr;

class ProtectionEngineObserver final : public mip::ProtectionEngine::Observer {
  public:
  ProtectionEngineObserver() {}
  void OnGetTemplatesSuccess(const vector<std::shared_ptr<mip::TemplateDescriptor>>& templateDescriptors, const shared_ptr<void>& context) override;
  void OnGetTemplatesFailure(const exception_ptr& Failure, const shared_ptr<void>& context) override;

};

Update "engine_observer.cpp", by selecting/deleting the generated engine_observer class implementation. Don't remove the preprocessor directives generated by the previous step (#pragma, #include). Then copy/paste the following source into the file, after any existing preprocessor directives:

#include "mip/protection/protection_profile.h"
#include "engine_observer.h"

using std::promise;
void ProtectionEngineObserver::OnGetTemplatesSuccess(const vector<shared_ptr<mip::TemplateDescriptor>>& templateDescriptors,const shared_ptr<void>& context) {
    auto loadPromise = static_cast<promise<vector<shared_ptr<mip::TemplateDescriptor>>>*>(context.get());
    loadPromise->set_value(templateDescriptors);
  };

  void ProtectionEngineObserver::OnGetTemplatesFailure(const exception_ptr& Failure, const shared_ptr<void>& context) {
    auto loadPromise = static_cast<promise<shared_ptr<mip::ProtectionProfile>>*>(context.get());
    loadPromise->set_exception(Failure);
  };

Optionally, use Ctrl+Shift+B (Build Solution) to run a test compile/link of your solution, to make sure it builds successfully before continuing.

The MIP SDK implements authentication using class extensibility, which provides a mechanism to share authentication work with the client application. The client must acquire a suitable OAuth2 access token, and provide to the MIP SDK at runtime.

Create an implementation for an authentication delegate, by extending the SDK's mip::AuthDelegate class, and overriding/implementing the mip::AuthDelegate::AcquireOAuth2Token() pure virtual function. Follow the steps detailed under File SDK Application Initialization Quickstart. The authentication delegate is instantiated and used later, by the Protection profile and Protection engine objects.

Now create an implementation for a consent delegate, by extending the SDK's mip::ConsentDelegate class, and overriding/implementing the mip::AuthDelegate::GetUserConsent() pure virtual function. Follow the steps detailed under File SDK Application Initialization Quickstart. The consent delegate is instantiated and used later, by the Protection profile and Protection engine objects.

Construct a Protection profile and engine

As mentioned, profile and engine objects are required for SDK clients using MIP APIs. Complete the coding portion of this Quickstart, by adding code to instantiate the profile and engine objects:

From Solution Explorer, open the .cpp file in your project that contains the implementation of the main() method. It defaults to the same name as the project containing it, which you specified during project creation.
Remove the generated implementation of main(). Don't remove preprocessor directives generated by Visual Studio during project creation (#pragma, #include). Append the following code after any preprocessor directives:

#include "mip/mip_init.h"
#include "mip/mip_context.h"  
#include "auth_delegate.h"
#include "consent_delegate.h"
#include "profile_observer.h"
#include"engine_observer.h"

using std::promise;
using std::future;
using std::make_shared;
using std::shared_ptr;
using std::string;
using std::cout;
using mip::ApplicationInfo;
using mip::ProtectionProfile;
using mip::ProtectionEngine;

int main(){

  // Construct/initialize objects required by the application's profile object
  // ApplicationInfo object (App ID, name, version)
  ApplicationInfo appInfo{"<application-id>",                    
                          "<application-name>",
                          "<application-version>"};

  std::shared_ptr<mip::MipConfiguration> mipConfiguration = std::make_shared<mip::MipConfiguration>(mAppInfo,
				                                                                                               "mip_data",
                                                                                      			         mip::LogLevel::Trace,
                                                                                                     false);

  std::shared_ptr<mip::MipContext> mMipContext = mip::MipContext::Create(mipConfiguration);

  auto profileObserver = make_shared<ProtectionProfileObserver>(); // Observer object
  auto authDelegateImpl = make_shared<AuthDelegateImpl>("<application-id>"); // Authentication delegate object (App ID)
  auto consentDelegateImpl = make_shared<ConsentDelegateImpl>(); // Consent delegate object

  // Construct/initialize profile object
  ProtectionProfile::Settings profileSettings(
    mMipContext,
    mip::CacheStorageType::OnDisk,      
    consentDelegateImpl,
    profileObserver);

  // Set up promise/future connection for async profile operations; load profile asynchronously
  auto profilePromise = make_shared<promise<shared_ptr<ProtectionProfile>>>();
  auto profileFuture = profilePromise->get_future();
  try
  {
    mip::ProtectionProfile::LoadAsync(profileSettings, profilePromise);
  }
  catch (const std::exception& e)
  {
    cout << "An exception occurred... are the Settings and ApplicationInfo objects populated correctly?\n\n"
          << e.what() << "'\n";
    system("pause");
    return 1;
  }

  auto profile = profileFuture.get();

  // Construct/initialize engine object
  ProtectionEngine::Settings engineSettings(       
     mip::Identity("<engine-account>"),         // Engine identity (account used for authentication)
     authDelegateImpl,                          // Reference to mip::AuthDelegate implementation
     "",                                        // ClientData field
     "en-US");                                  // Locale (default = en-US)

  // Set the engineId so it can be cached and reused. 
  engineSettings.SetEngineId("<engine-account>");

  // Set up promise/future connection for async engine operations; add engine to profile asynchronously
  auto enginePromise = make_shared<promise<shared_ptr<ProtectionEngine>>>();
  auto engineFuture = enginePromise->get_future();
  profile->AddEngineAsync(engineSettings, enginePromise);
  std::shared_ptr<ProtectionEngine> engine;

  try
  {
    engine = engineFuture.get();
  }
  catch (const std::exception& e)
  {
    cout << "An exception occurred... is the access token incorrect/expired?\n\n"
         << e.what() << "'\n";
    system("pause");
    return 1;
  }

  // Application shutdown. Null out profile and engine, call ReleaseAllResources();
  // Application may crash at shutdown if resources aren't properly released.
  engine = nullptr;
  profile = nullptr;
  mipContext.Shutdown();
  mipContext = nullptr;

  return 0;
}

Replace all placeholder values in the source code that you just pasted in, using string constants:

Placeholder	Value	Example
<application-id>	The Microsoft Entra Application ID (GUID) assigned to the application registered in step #2 of the "MIP SDK setup and configuration"(setup-configure-mip.md) article. Replace 2 instances.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<application-name>	A user-defined friendly name for your application. Must contain valid ASCII characters (excluding ';'), and ideally matches the application name you used in your Microsoft Entra registration.	`"AppInitialization"`
<application-version>	User-defined version info for your application. Must contain valid ASCII characters (excluding ';').	`"1.1.0.0"`
<engine-account>	The account used for the engine's identity. When you authenticate with a user account during token acquisition, it must match this value.	`"user1@tenant.onmicrosoft.com"`
<engine-state>	User-defined state to be associated with the engine.	`"My App State"`

Now do a final build of the application and resolve any errors. Your code should build successfully, but will not yet run correctly until you complete the next Quickstart. If you run the application, you see output similar to the following. The application would construct the Protection profile and Protection engine sucessfully but would not have fired authentication module and you won't have an access token yet, until you complete the next Quickstart.
```
 C:\MIP Sample Apps\ProtectionQS\Debug\ProtectionQS.exe (process 8252) exited with code 0.
 To automatically close the console when debugging stops, enable Tools->Options->Debugging->Automatically close the console when debugging stops.
 Press any key to close this window . . .
```

Next Steps

Now that your initialization code is complete, you're ready for the next quickstart, where you'll start to experience the MIP Protection SDK.

List protection templates

Quickstart: Client application initialization for Protection SDKs (C++)

Prerequisites

Create a Visual Studio solution and project

Implement observer classes to monitor the Protection profile and engine objects

Construct a Protection profile and engine

Next Steps

Feedback

Feedback

Additional resources

Quickstart: Client application initialization for Protection SDKs (C++)

Prerequisites

Create a Visual Studio solution and project

Implement observer classes to monitor the Protection profile and engine objects

Implement an authentication delegate and a consent delegate

Implement a consent delegate

Construct a Protection profile and engine

Next Steps

Feedback

Feedback

Additional resources