Microsoft Information Protection SDK - fetching the status of a file

In the MIP SDK File API, the static mip::FileHandler::GetFileStatus() function lets you fetch the status of a file without creating a file engine object, authenticating, or connecting to the internet. Provide the filename and create mipContext with a file path and stream.

Supported file types

  • Office file formats based on OPC (Office 2010 and later)
  • Legacy Office file formats (Office 2007)
  • PDF
  • Generic PFILE support
  • Files that support Adobe XMP
  • Email - .msg format

GetFileStatus() function

mip::FileHandler::GetFileStatus() lets developers fetch the status of a file. For the full list, consult the API reference.

This article covers the following methods:

  • mip::FileHandler::GetFileStatus() static function
  • FileStatus object that contains labeling or protection details for a file or container
  • IsProtected() property
  • IsLabeled() property
  • ContainsProtectedObject() property

Requirements

To create a FileHandler to work with a specific file, provide:

  • A mipContext
  • No file engine

Fetching the status of a file

To use the static mip::FileHandler::GetFileStatus() function, pass a file path or file stream and mipContext. This function doesn't require you to create a file engine, authenticate, or connect to the internet. This function is especially helpful for:

  • Getting the protection status of a file for decryption scenarios before creating an engine. Knowing the protection status ahead of time can let the developer skip the overhead of creating an engine if the file is already protected.
  • Getting the status of a file that might already have a label before creating an engine to try to read the label.
  • Getting the status of an MSG file that has attachments and that might need parsing or decryption along with the MSG file itself.

GetFileStatus() returns a fileStatus object with the following properties:

  • IsProtected() property - returns a Boolean value that indicates whether the file is protected or encrypted.
  • IsLabeled() property - returns a Boolean value that indicates whether the file is labeled.
  • ContainsProtectedObject() property - returns a Boolean value that indicates whether the file, container, or message contains a protected object.

Check all three properties because a file can have zero to all three properties and the permutations in between. Because GetFileStatus() doesn't require authentication or an engine to execute, the IsProtected(), IsLabeled(), and ContainsProtectedObject() methods reflect whether labeling or protection is present in a file. The methods don't validate whether the labeling or protection exists within a tenant or is usable by a user. To validate the label or protection, authenticate and create an engine.

    if (options.count("getfilestatus")) {
      auto fileStatus = GetFileStatus(filePath, fileStream, mipContext);
      if (fileStatus->IsProtected()) {
        cout << "File is protected" << endl;
      }
      if (fileStatus->IsLabeled()) {
        cout << "File is labeled" << endl;
      }
      if (fileStatus->ContainsProtectedObjects()) {
        cout << "File contains protected objects" << endl;
      }
      GetLabel(fileHandler);
      return EXIT_SUCCESS;
    }

    if (options.GetFileStatus) {
      var fileStatus = FileHandler.GetFileStatus(options.FilePath, mipContext);
      if (fileStatus.IsProtected()) {
        Console.WriteLine("The file is protected.");
      }
      if (fileStatus.IsLabeled()) {
        Console.WriteLine("The file is labeled.");
      }
      if (fileStatus.ContainsProtectedObjects()) {
        Console.WriteLine("The file contains protected objects.");
      }
      return true;
    }

 if (options.count("getfilestatus")) {
      auto fileStatus = GetFileStatus(filePath, fileStream, mipContext);
      if (fileStatus->IsProtected()) {
        cout << "File is protected" << endl;
      }
      if (fileStatus->IsLabeled()) {
        cout << "File is labeled" << endl;
      }
      if (fileStatus->ContainsProtectedObjects()) {
        cout << "File contains protected objects" << endl;
      }
      GetLabel(fileHandler);
      return EXIT_SUCCESS;
    }

Next steps

  • Last updated on