Quickstart: Set and get a sensitivity label (C++)

This Quickstart shows you how to use more of the MIP File SDKs. Using one of the sensitivity labels you listed in the previous Quickstart, you use a File handler to set/get the label on a file. The File handler class exposes various operations for setting/getting labels, or protection, for supported file types.

Prerequisites

If you haven't already, be sure to complete the following prerequisites before continuing:

• Complete Quickstart: List sensitivity labels (C++) first, which builds a starter Visual Studio solution, to list an organization's sensitivity labels. This "Set and get a sensitivity label" Quickstart builds on the previous one.
• Optionally: Review File handlers in the MIP SDK concepts.

Implement an observer class to monitor the File handler object

Similar to the observer you implemented (for the File profile and engine) in the Application initialization Quickstart, now you implement an observer class for a File handler object.

Create a basic implementation for a File handler observer, by extending the SDK's mip::FileHandler::Observer class. The observer is instantiated and used later, to monitor File handler operations.

1. Open the Visual Studio solution you worked on in the previous "Quickstart: List sensitivity labels (C++)" article.

2. 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 "filehandler_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.

3. 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 "filehandler_observer.h", by selecting/deleting the generated filehandler_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/file/file_engine.h"
     #include "mip/file/file_handler.h"
     
     class FileHandlerObserver final : public mip::FileHandler::Observer {
     public:
        FileHandlerObserver() { }
        // Observer implementation
        void OnCreateFileHandlerSuccess(const std::shared_ptr<mip::FileHandler>& fileHandler, const std::shared_ptr<void>& context) override;
        void OnCreateFileHandlerFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
        void OnCommitSuccess(bool committed, const std::shared_ptr<void>& context) override;
        void OnCommitFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;		
     };
     

   • Update "filehandler_observer.cpp", by selecting/deleting the generated filehandler_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:

     void FileHandlerObserver::OnCreateFileHandlerSuccess(const std::shared_ptr<mip::FileHandler>& fileHandler, const std::shared_ptr<void>& context) {
        auto promise = std::static_pointer_cast<std::promise<std::shared_ptr<mip::FileHandler>>>(context);
        promise->set_value(fileHandler);
     }
     
     void FileHandlerObserver::OnCreateFileHandlerFailure(const std::exception_ptr & error, const std::shared_ptr<void>& context) {
        auto promise = std::static_pointer_cast<std::promise<std::shared_ptr<mip::FileHandler>>>(context);
        promise->set_exception(error);
     }
     
     void FileHandlerObserver::OnCommitSuccess(bool committed, const std::shared_ptr<void>& context) {
        auto promise = std::static_pointer_cast<std::promise<bool>>(context);
        promise->set_value(committed);
     }
     
     void FileHandlerObserver::OnCommitFailure(const std::exception_ptr & error, const std::shared_ptr<void>& context) {
        auto promise = std::static_pointer_cast<std::promise<bool>>(context);
        promise->set_exception(error);
     }
     

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

Add logic to set and get a sensitivity label

Add logic to set and get a sensitivity label on a file, using the File engine object.

1. Using 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.

2. Add the following #include and using directives, below the corresponding existing directives, at the top of the file:

   #include "filehandler_observer.h" 
   #include "mip/file/file_handler.h" 
   
   using mip::FileHandler;
   

3. Toward the end of the main() body, below system("pause"); and above return 0; (where you left off in the previous Quickstart), insert the following code:

   // Set up async FileHandler for input file operations
   string inputFilePath = "<input-file-path>";
   string actualFilePath = "<content-identifier>";
   std::shared_ptr<FileHandler> handler;
   try
   {
        auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
        auto handlerFuture = handlerPromise->get_future();
        engine->CreateFileHandlerAsync(
             inputFilePath,
             actualFilePath,                       
             true, 
             std::make_shared<FileHandlerObserver>(), 
             handlerPromise);
        handler = handlerFuture.get();
   }
   catch (const std::exception& e)
   {
        cout << "An exception occurred... did you specify a valid input file path?\n\n" << e.what() << "'\n";
        system("pause");
        return 1;
   }
   
   // Set a label on input file
   try
   {
        string labelId = "<label-id>";
        cout << "\nApplying Label ID " << labelId << " to " << filePathIn << endl;
        mip::LabelingOptions labelingOptions(mip::AssignmentMethod::PRIVILEGED);
        handler->SetLabel(engine->GetLabelById(labelId), labelingOptions, new ProtectionSettings());
   }
   catch (const std::exception& e)
   {
        cout << "An exception occurred... did you specify a valid label ID?\n\n" << e.what() << "'\n";
        system("pause");
        return 1; 
   }
   
   // Commit changes, save as a different/output file
   string filePathOut = "<output-file-path>";
   try
   {
    	cout << "Committing changes" << endl;
        auto commitPromise = std::make_shared<std::promise<bool>>();
        auto commitFuture = commitPromise->get_future();
        handler->CommitAsync(filePathOut, commitPromise);
    	if (commitFuture.get()) {
    		cout << "\nLabel committed to file: " << filePathOut << endl;
    	}
    	else {
    		cout << "Failed to label: " + filePathOut << endl;
    		return 1;
    	}
   }
   catch (const std::exception& e)
   {
        cout << "An exception occurred... did you specify a valid commit file path?\n\n" << e.what() << "'\n";
        system("pause");
        return 1;
   }
   system("pause");
   
   // Set up async FileHandler for output file operations
   actualFilePath = "<content-identifier>";
   try
   {
        auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
        auto handlerFuture = handlerPromise->get_future();
        engine->CreateFileHandlerAsync(
             filePathOut,
             actualFilePath,
             true,
             std::make_shared<FileHandlerObserver>(),
             handlerPromise);
   
        handler = handlerFuture.get();
   }
   catch (const std::exception& e)
   {
        cout << "An exception occurred... did you specify a valid output file path?\n\n" << e.what() << "'\n";
        system("pause");
        return 1;
   }
   
   // Get the label from output file
   try
   {
        cout << "\nGetting the label committed to file: " << filePathOut << endl;
        auto label = handler->GetLabel();
        cout << "Name: " + label->GetLabel()->GetName() << endl;
        cout << "Id: " + label->GetLabel()->GetId() << endl;
   }
   catch (const std::exception& e)
   {
        cout << "An exception occurred... did you specify a valid label ID?\n\n" << e.what() << "'\n";
        system("pause");
        return 1;
   }
   system("pause");
   

4. Toward the end of main() find the application shutdown block created in the first quickstart and uncomment the handler line:

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

5. Replace the placeholder values in the source code that you as follows, using string constants:

   Placeholder	Value
   <input-file-path>	The full path to a test input file, for example: "c:\\Test\\Test.docx".
   <content-identifier>	A human-readable identifier for the content. For example: for a file, consider path\filename: "c:\Test\Test.docx" for an email, consider subject:sender : "RE: Audit design:[email protected]"
   <label-id>	A sensitivity label ID, copied from the console output in the previous Quickstart, for example: "f42a3342-8706-4288-bd31-ebb85995028z".
   <output-file-path>	The full path to the output file, which will be a labeled copy of the input file, for example: "c:\\Test\\Test_labeled.docx".

Build and test the application

Build and test your client application.

1. Use F6 (Build Solution) to build your client application. If you have no build errors, use F5 (Start debugging) to run your application.

2. If your project builds and runs successfully, the application prompts for an access token, each time the SDK calls your AcquireOAuth2Token() method. As you did previously in the "List sensitivity labels" Quickstart, run your PowerShell script to acquire the token each time, using the values provided for $authority and $resourceUrl.

   Run the PowerShell script to generate an access token using the following values, then copy/paste it below:
   
   Sensitivity labels for your organization:
   Non-Business : 87ba5c36-17cf-14793-bbc2-bd5b3a9f95cz
   Public : 83867195-f2b8-2ac2-b0b6-6bb73cb33afz
   General : f42a3342-8706-4288-bd31-ebb85995028z
   Confidential : 074e457c-5848-4542-9a6f-34a182080e7z
   Highly Confidential : f55c2dea-db0f-47cd-8520-a52e1590fb6z
   Press any key to continue . . .
   
   Applying Label ID 074e457c-5848-4542-9a6f-34a182080e7z to c:\Test\Test.docx
   Committing changes
   
   Label committed to file: c:\Test\Test_labeled.docx
   Press any key to continue . . .
   
   Getting the label committed to file: c:\Test\Test_labeled.docx
   Name: Confidential
   Id: 074e457c-5848-4542-9a6f-34a182080e7z
   Press any key to continue . . .
   

You can verify the application of the label, by opening the output file and visually inspecting the document's information protection settings.