Android 代码示例Android code examples

重要

弃用2020年3月之前发布的 Microsoft Rights Management Service SDK 版本;必须将使用早期版本的应用程序更新为使用三月2020版。Versions of the Microsoft Rights Management Service SDK released prior to March 2020 are deprecated; applications using earlier versions must be updated to use the March 2020 release. 有关完整详细信息,请参阅弃用通知For full details, see the deprecation notice.

不会为 Microsoft Rights Management 服务 SDK 规划进一步的增强功能。No further enhancements are planned for the Microsoft Rights Management Service SDK. 我们强烈建议采用Microsoft Information PROTECTION SDK进行分类、标记和保护服务。We strongly recommend adoption of the Microsoft Information Protection SDK for classification, labeling, and protection services.

本文介绍了如何为 Android 版 RMS SDK 编码元素。This article shows how to code elements for the Android version of the RMS SDK.

注意: 在本文中,MSIPC__ (Microsoft Information Protection and Control) 一词是指客户端流程。Note In this article, The term MSIPC (Microsoft Information Protection and Control) refers to the client process.

使用 Microsoft Rights Management SDK 4.2 - 重要方案Using the Microsoft Rights Management SDK 4.2 - key scenarios

这些代码示例摘自较大的示例应用,即对熟悉此 SDK 十分重要的开发方案。These code samples are taken from a larger sample application representing development scenarios important to your orientation to this SDK. 它们展示了如何使用以下对象:They show how to use:

  • Microsoft 受保护的文件格式(亦称为“受保护的文件”__。The Microsoft Protected File format, also called a protected file.
  • 自定义受保护的文件格式Custom protected file formats
  • 自定义用户界面 (UI) 控件Custom user interface (UI) controls

MSIPCSampleApp** 示例应用可与适用于 Android 操作系统的此 SDK 配合使用。The MSIPCSampleApp sample application is available for use with this SDK for the Android operating system. 若要了解详细信息,请参阅 rms-sdk-ui-for-androidTo learn more, see rms-sdk-ui-for-android.

方案:使用受 RMS 保护的文件Scenario: Consume an RMS protected file

  • 第 1 步:创建 ProtectedFileInputStreamStep 1: Create a ProtectedFileInputStream.

    MsipcAuthenticationCallback.javaSource: MsipcAuthenticationCallback.java

    说明:实例化 ProtectedFileInputStream 对象,并实现服务身份验证。Description: Instantiate a ProtectedFileInputStream object and implement service authentication. 使用 AuthenticationRequestCallback 获取令牌,具体是通过将 AuthenticationRequestCallback**** 实例作为参数 mRmsAuthCallback** 传递到 MSIPC API。Use the AuthenticationRequestCallback to get a token by passing an instance of AuthenticationRequestCallback, as the parameter mRmsAuthCallback, to the MSIPC API. 请参阅以下示例代码节结尾附近的 ProtectedFileInputStream.create 调用。See the call to ProtectedFileInputStream.create near the end of the following example code section.

        public void startContentConsumptionFromPtxtFileFormat(InputStream inputStream)
        {
            CreationCallback<ProtectedFileInputStream> protectedFileInputStreamCreationCallback =
              new CreationCallback<ProtectedFileInputStream>()
            {
                @Override
                public Context getContext()
                {
                   …
               }
    
                @Override
                public void onCancel()
                {
                   …
                }
    
                @Override
                public void onFailure(ProtectionException e)
                {
                   …
                }
    
                @Override
                public void onSuccess(ProtectedFileInputStream protectedFileInputStream)
                {
                   …
                   …
                    byte[] dataChunk = new byte[16384];
                    try
                    {
                        while ((nRead = protectedFileInputStream.read(dataChunk, 0,
                                dataChunk.length)) != -1)
                        {
                            …
                        }
                         …
                        protectedFileInputStream.close();
                    }
                    catch (IOException e)
                    {
                      …
                    }
              }
            };
            try
            {
               …
                ProtectedFileInputStream.create(inputStream, null, mRmsAuthCallback,
                                                PolicyAcquisitionFlags.NONE,
                                                protectedFileInputStreamCreationCallback);
            }
            catch (com.microsoft.rightsmanagement.exceptions.InvalidParameterException e)
            {
                …
            }
        }
    
  • 第 2 步:使用 Active Directory Authentication Library (ADAL) 设置身份验证。Step 2: Set up authentication using the Active Directory Authentication Library (ADAL).

    msipcauthenticationcallback.javaSource: MsipcAuthenticationCallback.java.

    说明:在这一步中,需要使用 ADAL 实现包含示例身份验证参数的 AuthenticationRequestCallbackDescription: This step uses ADAL to implement an AuthenticationRequestCallback with example authentication parameters. 若要了解详细信息,请参阅 Azure AD Authentication Library (ADAL)To learn more, see the Azure AD Authentication Library (ADAL).

         class MsipcAuthenticationCallback implements AuthenticationRequestCallback
         {
    
         …
    
         @Override
         public void getToken(Map<String, String> authenticationParametersMap,
                              final AuthenticationCompletionCallback authenticationCompletionCallbackToMsipc)
         {
             String authority = authenticationParametersMap.get("oauth2.authority");
             String resource = authenticationParametersMap.get("oauth2.resource");
             String userId = authenticationParametersMap.get("userId");
             final String userHint = (userId == null)? "" : userId;
             AuthenticationContext authenticationContext = App.getInstance().getAuthenticationContext();
             if (authenticationContext == null || !authenticationContext.getAuthority().equalsIgnoreCase(authority))
             {
                 try
                 {
                     authenticationContext = new AuthenticationContext(App.getInstance().getApplicationContext(), authority, …);
                     App.getInstance().setAuthenticationContext(authenticationContext);
                 }
                 catch (NoSuchAlgorithmException e)
                 {
                     …
                     authenticationCompletionCallbackToMsipc.onFailure();
                 }
                 catch (NoSuchPaddingException e)
                 {
                     …
                     authenticationCompletionCallbackToMsipc.onFailure();
                 }
            }
             App.getInstance().getAuthenticationContext().acquireToken(mParentActivity, resource, mClientId, mRedirectURI, userId, mPromptBehavior,
                            "&USERNAME=" + userHint, new AuthenticationCallback<AuthenticationResult>()
                             {
                                 @Override
                                 public void onError(Exception exc)
                                 {
                                     …
                                     if (exc instanceof AuthenticationCancelError)
                                     {
                                          …
                                         authenticationCompletionCallbackToMsipc.onCancel();
                                     }
                                     else
                                     {
                                          …
                                         authenticationCompletionCallbackToMsipc.onFailure();
                                     }
                                 }
    
                                 @Override
                                 public void onSuccess(AuthenticationResult result)
                                 {
                                     …
                                     if (result == null || result.getAccessToken() == null
                                             || result.getAccessToken().isEmpty())
                                     {
                                          …
                                     }
                                     else
                                     {
                                         // request is successful
                                         …
                                         authenticationCompletionCallbackToMsipc.onSuccess(result.getAccessToken());
                                     }
                                 }
                             }
    
                             );
                       }
    
  • 步骤 3:通过 UserPolicy.accessCheck 方法检查此用户对于该内容是否具有 Edit 权限。Step 3: Check if the Edit right exists for this user with this content via the UserPolicy.accessCheck method.

    TextEditorFragment.javaSource: TextEditorFragment.java

         //check if user has edit rights and apply enforcements
                if (!mUserPolicy.accessCheck(EditableDocumentRights.Edit))
                {
                    mTextEditor.setFocusableInTouchMode(false);
                    mTextEditor.setFocusable(false);
                    mTextEditor.setEnabled(false);
                    …
                }
    

方案:使用模板创建新的受保护文件Scenario: Create a new protected file using a template

此方案首先获取模板列表,选择第一个模板以创建策略,然后创建并写入新的受保护的文件。This scenario begins with getting a list of templates, selecting the first one to create a policy, then creates and writes to the new protected file.

  • 步骤 1:通过 TemplateDescriptor 对象获取模板列表。Step 1: Get list of templates via a TemplateDescriptor object.

    MsipcTaskFragment.javaSource: MsipcTaskFragment.java

    CreationCallback<List<TemplateDescriptor>> getTemplatesCreationCallback = new CreationCallback<List<TemplateDescriptor>>()
      {
          @Override
          public Context getContext()
          {
              …
          }
    
          @Override
          public void onCancel()
          {
              …
          }
    
          @Override
          public void onFailure(ProtectionException e)
          {
              …
          }
    
          @Override
          public void onSuccess(List<TemplateDescriptor> templateDescriptors)
          {
             …
          }
      };
      try
      {
              …
          mIAsyncControl = TemplateDescriptor.getTemplates(emailId, mRmsAuthCallback, getTemplatesCreationCallback);
      }
      catch (com.microsoft.rightsmanagement.exceptions.InvalidParameterException e)
      {
              …
      }
    
  • 步骤 2:使用列表中的第一个模板创建 UserPolicyStep 2: Create a UserPolicy using the first template in the list.

    MsipcTaskFragment.javaSource: MsipcTaskFragment.java

      CreationCallback<UserPolicy> userPolicyCreationCallback = new CreationCallback<UserPolicy>()
      {
          @Override
          public Context getContext()
          {
              …
          }
    
          @Override
          public void onCancel()
          {
              …
          }
    
          @Override
          public void onFailure(ProtectionException e)
          {
              …
          }
    
          @Override
          public void onSuccess(final UserPolicy item)
          {
              …
          }
      };
      try
      {
           …
          mIAsyncControl = UserPolicy.create((TemplateDescriptor)selectedDescriptor, mEmailId, mRmsAuthCallback,
                            UserPolicyCreationFlags.NONE, userPolicyCreationCallback);
           …
      }
      catch (InvalidParameterException e)
      {
              …
      }
    
  • 步骤 3:创建 ProtectedFileOutputStream 并向其中写入内容。Step 3: Create a ProtectedFileOutputStream and write content to it.

    MsipcTaskFragment.javaSource: MsipcTaskFragment.java

    private void createPTxt(final byte[] contentToProtect)
        {
             …
            CreationCallback<ProtectedFileOutputStream> protectedFileOutputStreamCreationCallback = new CreationCallback<ProtectedFileOutputStream>()
            {
                @Override
                public Context getContext()
                {
                 …
                }
    
                @Override
                public void onCancel()
                {
                 …
                }
    
                @Override
                public void onFailure(ProtectionException e)
                {
                 …
                }
    
                @Override
                public void onSuccess(ProtectedFileOutputStream protectedFileOutputStream)
                {
                    try
                    {
                        // write to this stream
                        protectedFileOutputStream.write(contentToProtect);
                        protectedFileOutputStream.flush();
                        protectedFileOutputStream.close();
                        …
                    }
                    catch (IOException e)
                    {
                        …
                    }
                }
            };
            try
            {
                File file = new File(filePath);
                outputStream = new FileOutputStream(file);
                mIAsyncControl = ProtectedFileOutputStream.create(outputStream, mUserPolicy, originalFileExtension,
                        protectedFileOutputStreamCreationCallback);
            }
            catch (FileNotFoundException e)
            {
                 …
            }
            catch (InvalidParameterException e)
            {
                 …
            }
        }
    

方案:打开自定义受保护的文件Scenario: Open a custom protected file

  • 步骤 1:从 serializedContentPolicy 创建 UserPolicyStep 1: Create a UserPolicy from a serializedContentPolicy.

    MsipcTaskFragment.javaSource: MsipcTaskFragment.java

    CreationCallback<UserPolicy> userPolicyCreationCallbackFromSerializedContentPolicy = new CreationCallback<UserPolicy>()
            {
                @Override
                public void onSuccess(UserPolicy userPolicy)
                {
                  …
                }
    
                @Override
                public void onFailure(ProtectionException e)
                {
                  …
                }
    
                @Override
                public void onCancel()
                {
                  …
                }
    
                @Override
                public Context getContext()
                {
                  …
                }
            };
            try
            {
                ...
    
                // Read the serializedContentPolicyLength from the inputStream.
                long serializedContentPolicyLength = readUnsignedInt(inputStream);
    
                // Read the PL bytes from the input stream using the PL size.
                byte[] serializedContentPolicy = new byte[(int)serializedContentPolicyLength];
                inputStream.read(serializedContentPolicy);
    
                ...
    
                UserPolicy.acquire(serializedContentPolicy, null, mRmsAuthCallback, PolicyAcquisitionFlags.NONE,
                userPolicyCreationCallbackFromSerializedContentPolicy);
            }
            catch (com.microsoft.rightsmanagement.exceptions.InvalidParameterException e)
            {
            ...
            }
            catch (IOException e)
            {
            ...
            }
    
  • 步骤 2:使用来自 步骤 1UserPolicy 创建 CustomProtectedInputStreamStep 2: Create a CustomProtectedInputStream using the UserPolicy from Step 1.

    MsipcTaskFragment.javaSource: MsipcTaskFragment.java

      CreationCallback<CustomProtectedInputStream> customProtectedInputStreamCreationCallback = new CreationCallback<CustomProtectedInputStream>()
      {
         @Override
         public Context getContext()
         {
             …
         }
    
         @Override
         public void onCancel()
         {
             …
         }
    
         @Override
         public void onFailure(ProtectionException e)
         {
             …
         }
    
         @Override
         public void onSuccess(CustomProtectedInputStream customProtectedInputStream)
         {
            …
    
             byte[] dataChunk = new byte[16384];
             try
             {
                 while ((nRead = customProtectedInputStream.read(dataChunk, 0, dataChunk.length)) != -1)
                 {
                      …
                 }
                  …
                 customProtectedInputStream.close();
             }
             catch (IOException e)
             {
                …
             }
             …
         }
     };
    
    try
    {
      ...
    
      // Retrieve the encrypted content size.
      long encryptedContentLength = readUnsignedInt(inputStream);
    
      updateTaskStatus(new TaskStatus(TaskState.Starting, "Consuming content", true));
    
      CustomProtectedInputStream.create(userPolicy, inputStream,
                                     encryptedContentLength,
                                     customProtectedInputStreamCreationCallback);
    }
    catch (com.microsoft.rightsmanagement.exceptions.InvalidParameterException e)
    {
      ...
    }
    catch (IOException e)
    {
      ...
    }
    
  • 步骤 3:将内容从 CustomProtectedInputStream 读取到 mDecryptedContent 中,然后关闭。Step 3: Read content from the CustomProtectedInputStream into mDecryptedContent then close.

    MsipcTaskFragment.javaSource: MsipcTaskFragment.java

    @Override
    public void onSuccess(CustomProtectedInputStream customProtectedInputStream)
    {
      mUserPolicy = customProtectedInputStream.getUserPolicy();
      ByteArrayOutputStream buffer = new ByteArrayOutputStream();
    
      int nRead;
      byte[] dataChunk = new byte[16384];
    
      try
      {
        while ((nRead = customProtectedInputStream.read(dataChunk, 0,
                                                            dataChunk.length)) != -1)
        {
           buffer.write(dataChunk, 0, nRead);
        }
    
        buffer.flush();
        mDecryptedContent = new String(buffer.toByteArray(), Charset.forName("UTF-8"));
    
        buffer.close();
        customProtectedInputStream.close();
      }
      catch (IOException e)
      {
        ...
      }
    }
    

方案:使用自定义策略创建自定义受保护的文件Scenario: Create a custom protected file using a custom policy

  • 步骤 1:在用户提供了电子邮件地址的情况下,创建策略描述符。Step 1: With an email address provided by the user, create a policy descriptor.

    MsipcTaskFragment.javaSource: MsipcTaskFragment.java

    说明:实际上,将使用用户在设备界面中输入的内容创建以下对象;UserRightsPolicyDescriptorDescription: In practice, the following objects would be created by using user inputs from the device interface; UserRights and PolicyDescriptor.

      // create userRights list
      UserRights userRights = new UserRights(Arrays.asList("consumer@domain.com"),
        Arrays.asList( CommonRights.View, EditableDocumentRights.Print));
      ArrayList<UserRights> usersRigthsList = new ArrayList<UserRights>();
      usersRigthsList.add(userRights);
    
      // Create PolicyDescriptor using userRights list
      PolicyDescriptor policyDescriptor = PolicyDescriptor.createPolicyDescriptorFromUserRights(
                                                             usersRigthsList);
      policyDescriptor.setOfflineCacheLifetimeInDays(10);
      policyDescriptor.setContentValidUntil(new Date());
    
  • 步骤 2:通过策略描述符 selectedDescriptor 创建自定义 UserPolicyStep 2: Create a custom UserPolicy from the policy descriptor, selectedDescriptor.

    MsipcTaskFragment.javaSource: MsipcTaskFragment.java

       mIAsyncControl = UserPolicy.create((PolicyDescriptor)selectedDescriptor,
         mEmailId, mRmsAuthCallback, UserPolicyCreationFlags.NONE, userPolicyCreationCallback);
    
  • 步骤 3:创建内容并写入 CustomProtectedOutputStream,然后关闭。Step 3: Create and write content to the CustomProtectedOutputStream and then close.

    MsipcTaskFragment.javaSource: MsipcTaskFragment.java

    File file = new File(filePath);
        final OutputStream outputStream = new FileOutputStream(file);
        CreationCallback<CustomProtectedOutputStream> customProtectedOutputStreamCreationCallback = new CreationCallback<CustomProtectedOutputStream>()
        {
            @Override
            public Context getContext()
            {
              …
            }
    
            @Override
            public void onCancel()
            {
              …
            }
    
            @Override
            public void onFailure(ProtectionException e)
            {
              …
            }
    
            @Override
            public void onSuccess(CustomProtectedOutputStream protectedOutputStream)
            {
                try
                {
                    // write serializedContentPolicy
                    byte[] serializedContentPolicy = mUserPolicy.getSerializedContentPolicy();
                    writeLongAsUnsignedIntToStream(outputStream, serializedContentPolicy.length);
                    outputStream.write(serializedContentPolicy);
                    // write encrypted content
                    if (contentToProtect != null)
                    {
                        writeLongAsUnsignedIntToStream(outputStream,
                                CustomProtectedOutputStream.getEncryptedContentLength(contentToProtect.length,
                                        protectedOutputStream.getUserPolicy()));
                        protectedOutputStream.write(contentToProtect);
                        protectedOutputStream.flush();
                        protectedOutputStream.close();
                    }
                    else
                    {
                        outputStream.flush();
                        outputStream.close();
                    }
                    …
                }
                catch (IOException e)
                {
                  …
                }
            }
        };
        try
        {
            mIAsyncControl = CustomProtectedOutputStream.create(outputStream, mUserPolicy,
                    customProtectedOutputStreamCreationCallback);
        }
        catch (InvalidParameterException e)
        {
          …
        }