Exemplos de código de iOS/OS XiOS/OS X code examples

Este tópico apresenta-lhe elementos de código importantes para a versão iOS/OS X do SDK RMS.This topic will introduce you to important code elements for the iOS/OS X version of the RMS SDK.

Nota: no código de exemplo e nas descrições que se seguem, utilizamos o termo MSIPC (Microsoft Information Protection and Control) para referenciar o processo de cliente.Note In the example code and descriptions that follow, we use the term MSIPC (Microsoft Information Protection and Control) to reference the client process.

Utilizar o SDK Microsoft Rights Management 4.2 – cenários principaisUsing the Microsoft Rights Management SDK 4.2 - key scenarios

Seguem-se exemplos de código do Objetivo C de uma aplicação de exemplo maior que representam cenários de desenvolvimento importantes para se orientar neste SDK.Following are Objective C code examples from a larger sample application representing development scenarios important to your orientation to this SDK. Estes demonstram a utilização do formato de Ficheiro Protegido da Microsoft referido como ficheiro protegido, a utilização de formatos de ficheiros protegidos personalizados e a utilização de controlos de IU personalizados.These demonstrate; use of Microsoft Protected File format referred to as protected file , use of custom protected file formats, and use of custom UI controls.

Cenário: consumir um ficheiro de RMS protegidoScenario: Consume an RMS protected file

  • Passo 1: criar um objeto MSProtectedDataStep 1: Create an MSProtectedData object

    Descrição: instanciar um objeto MSProtectedData através do respetivo método de criação que implementa o serviço de autenticação com o MSAuthenticationCallback para obter um token ao transferir uma instância de MSAuthenticationCallback, como o parâmetro authenticationCallback, para a API de MSIPC.Description: Instantiate an MSProtectedData object, through its create method which implements service authentication using the MSAuthenticationCallback to get a token by passing an instance of MSAuthenticationCallback, as the parameter authenticationCallback, to the MSIPC API. Consulte a chamada para MSProtectedData protectedDataWithProtectedFile na secção de código de exemplo seguinte.See the call to MSProtectedData protectedDataWithProtectedFile in the following example code section.

      + (void)consumePtxtFile:(NSString *)path authenticationCallback:(id<MSAuthenticationCallback>)authenticationCallback
      {
          // userId can be provided as a hint for authentication
          [MSProtectedData protectedDataWithProtectedFile:path
                                               userId:nil
                               authenticationCallback:authenticationCallback
                                              options:Default
                                      completionBlock:^(MSProtectedData *data, NSError *error)
          {
              //Read the content from the ProtectedData, this will decrypt the data
              NSData *content = [data retrieveData];
          }];
      }
    
  • Passo 2: configurar a autenticação com a Active Directory Authentication Library (ADAL).Step 2: Setup authentication using the Active Directory Authentication Library (ADAL).

    Descrição: neste passo, verá a ADAL utilizada para implementar um MSAuthenticationCallback com parâmetros de autenticação de exemplo.Description: In this step you will see ADAL used to implement an MSAuthenticationCallback with example authentication parameters. Para obter mais informações sobre a utilização da ADAL, consulte a Azure AD Authentication Library (ADAL).For more information on using ADAL, see the Azure AD Authentication Library (ADAL).

    // AuthenticationCallback holds the necessary information to retrieve an access token.
    @interface MsipcAuthenticationCallback : NSObject<MSAuthenticationCallback>
    
    @end
    
    @implementation MsipcAuthenticationCallback
    
    - (void)accessTokenWithAuthenticationParameters:
           (MSAuthenticationParameters *)authenticationParameters
                                  completionBlock:
           (void(^)(NSString *accessToken, NSError *error))completionBlock
    {
        ADAuthenticationError *error;
        ADAuthenticationContext* context = [
            ADAuthenticationContext authenticationContextWithAuthority:authenticationParameters.authority
                                                              error:&error
        ];
        NSString *appClientId = @”com.microsoft.sampleapp”;
        NSURL *redirectURI = [NSURL URLWithString:@"local://authorize"];
        // Retrieve token using ADAL
        [context acquireTokenWithResource:authenticationParameters.resource
                               clientId:appClientId
                            redirectUri:redirectURI
                                 userId:authenticationParameters.userId
                        completionBlock:^(ADAuthenticationResult *result) {
                            if (result.status != AD_SUCCEEDED)
                            {
                                NSLog(@"Auth Failed");
                                completionBlock(nil, result.error);
                            }
                            else
                            {
                                completionBlock(result.accessToken, result.error);
                            }
                        }];
     }
    
  • Passo 3: verificar se o direito de Edição existe para este utilizador com estes conteúdos através do método MSUserPolicy accessCheck de um objeto MSUserPolicy.Step 3: Check if the Edit right exists for this user with this content via the MSUserPolicy accessCheck method of a MSUserPolicy object.

    - (void)accessCheckWithProtectedData:(MSProtectedData *)protectedData
    {
        //check if user has edit rights and apply enforcements
        if (!protectedData.userPolicy.accessCheck(EditableDocumentRights.Edit))
        {
            // enforce on the UI
            textEditor.focusableInTouchMode = NO;
            textEditor.focusable = NO;
            textEditor.enabled = NO;
        }
    }
    

Cenário: criar um novo ficheiro protegido através de um modeloScenario: Create a new protected file using a template

Este cenário começa com a obtenção de uma lista de modelos, MSTemplateDescriptor, ao selecionar o primeiro para criar uma política e, em seguida, ao criar e escrever no novo ficheiro protegido.This scenario begins with getting a list of templates, MSTemplateDescriptor, selecting the first one to create a policy, then creating and writing to the new protected file.

  • Passo 1: obter lista de modelosStep 1: Get list of templates

    + (void)templateListUsageWithAuthenticationCallback:(id<MSAuthenticationCallback>)authenticationCallback
    {
        [MSTemplateDescriptor templateListWithUserId:@"user@domain.com"
                        authenticationCallback:authenticationCallback
                               completionBlock:^(NSArray/*MSTemplateDescriptor*/ *templates, NSError *error)
                               {
                                 // use templates array of MSTemplateDescriptor (Note: will be nil on error)
                               }];
    }
    
  • Passo 2: criar um MSUserPolicy com o primeiro modelo na lista.Step 2: Create a MSUserPolicy using the first template in the list.

    + (void)userPolicyCreationFromTemplateWithAuthenticationCallback:(id<MSAuthenticationCallback>)authenticationCallback
    {
        [MSUserPolicy userPolicyWithTemplateDescriptor:[templates objectAtIndex:0]
                                        userId:@"user@domain.com"
                                 signedAppData:nil
                        authenticationCallback:authenticationCallback
                                       options:None
                               completionBlock:^(MSUserPolicy *userPolicy, NSError *error)
        {
        // use userPolicy (Note: will be nil on error)
        }];
    }
    
  • Passo 3: criar um MSMutableProtectedData e escrever os conteúdos no mesmo.Step 3: Create a MSMutableProtectedData and write content to it.

    + (void)createPtxtWithUserPolicy:(MSUserPolicy *)userPolicy contentToProtect:(NSData *)contentToProtect
    {
        // create an MSMutableProtectedData to write content
        [contentToProtect protectedDataInFile:filePath
                    originalFileExtension:kDefaultTextFileExtension
                           withUserPolicy:userPolicy
                          completionBlock:^(MSMutableProtectedData *data, NSError *error)
        {
         // use data (Note: will be nil on error)
        }];
    }
    

Cenário: abrir um ficheiro protegido personalizadoScenario: Open a custom protected file

  • Passo 1: criar um MSUserPolicy a partir de um serializedContentPolicy.Step 1: Create a MSUserPolicy from a serializedContentPolicy.

    + (void)userPolicyWith:(NSData *)protectedData
    authenticationCallback:(id<MSAuthenticationCallback>)authenticationCallback
    {
        // Read header information from protectedData and extract the  PL
        /*-------------------------------------------
        | PL length | PL | ContetSizeLength |
        -------------------------------------------*/
        NSUInteger serializedPolicySize;
        NSMutableData *serializedPolicy;
        [protectedData getBytes:&serializedPolicySize length:sizeof(serializedPolicySize)];
        [protectedData getBytes:[serializedPolicy mutableBytes] length:serializedPolicySize];
    
        // Get the user policy , this is an async method as it hits the REST service
        // for content key and usage restrictions
        // userId provided as a hint for authentication
        [MSUserPolicy userPolicyWithSerializedPolicy:serializedPolicy
                                          userId:@"user@domain.com"
                          authenticationCallback:authenticationCallback
                                         options:Default
                                 completionBlock:^(MSUserPolicy *userPolicy,
                                                   NSError *error)
        {
    
        }];
     }
    
  • Passo 2: criar um MSCustomProtectedData com o MSUserPolicy do Passo 1 e ler a partir do mesmo.Step 2: Create a MSCustomProtectedData using the MSUserPolicy from Step 1 and read from it.

    + (void)customProtectedDataWith:(NSData *)protectedData
    {
        // Read header information from protectedData and extract the  protectedContentSize
        /*-------------------------------------------
        | PL length | PL | ContetSizeLength |
        -------------------------------------------*/
        NSUInteger protectedContentSize;
        [protectedData getBytes:&protectedContentSize
                     length:sizeof(protectedContentSize)];
    
        // Create the MSCustomProtector used for decrypting the content
        // The content start position is the header length
        [MSCustomProtectedData customProtectedDataWithPolicy:userPolicy
                                           protectedData:protectedData
                                    contentStartPosition:sizeof(NSUInteger) + serializedPolicySize
                                             contentSize:protectedContentSize
                                         completionBlock:^(MSCustomProtectedData *customProtector,
                                                           NSError *error)
        {
         //Read the content from the custom protector, this will decrypt the data
         NSData *content = [customProtector retrieveData];
         NSLog(@"%@", content);
        }];
     }
    

Cenário: criar um ficheiro protegido personalizado utilizando uma política personalizada (ad hoc)Scenario: Create a custom protected file using a custom (ad-hoc) policy

  • Passo 1: com um endereço de e-mail fornecido pelo utilizador, criar um descritor de política.Step 1: With an email address provided by the user, create a policy descriptor.

    Descrição: na prática, seria possível criar os seguintes objetos com entradas do utilizador a partir da interface do dispositivo; MSUserRights e MSPolicyDescriptor.Description: In practice the following objects would be created by using user inputs from the device interface; MSUserRights and MSPolicyDescriptor.

    + (void)policyDescriptor
    {
        MSUserRights *userRights = [[MSUserRights alloc] initWithUsers:[NSArray arrayWithObjects: @"user1@domain.com", @"user2@domain.com", nil] rights:[MSEmailRights all]];
    
        MSPolicyDescriptor *policyDescriptor = [[MSPolicyDescriptor alloc] initWithUserRights:[NSArray arrayWithObjects:userRights, nil]];
        policyDescriptor.contentValidUntil = [[NSDate alloc] initWithTimeIntervalSinceNow:NSTimeIntervalSince1970 + 3600.0];
        policyDescriptor.offlineCacheLifetimeInDays = 10;
    }
    
  • Passo 2: criar um MSUserPolicy personalizado do descritor de política, selectedDescriptor.Step 2: Create a custom MSUserPolicy from the policy descriptor, selectedDescriptor.

    + (void)userPolicyWithPolicyDescriptor:(MSPolicyDescriptor *)policyDescriptor
    {
        [MSUserPolicy userPolicyWithPolicyDescriptor:policyDescriptor
                                      userId:@"user@domain.com"
                      authenticationCallback:authenticationCallback
                                     options:None
                             completionBlock:^(MSUserPolicy *userPolicy, NSError *error)
        {
          // use userPolicy (Note: will be nil on error)
        }];
    }
    
  • Passo 3: criar e escrever os conteúdos no MSMutableCustomProtectedData e fechar.Step 3: Create and write content to the MSMutableCustomProtectedData and then close.

    + (void)mutableCustomProtectedData:(NSMutableData *)backingData policy:(MSUserPolicy *)policy contentToProtect:(NSString *)contentToProtect
    {
        //Get the serializedPolicy from a given policy
        NSData *serializedPolicy = [policy serializedPolicy];
    
        // Write header information to backing data including the PL
        // ------------------------------------
        // | PL length | PL | ContetSizeLength |
        // -------------------------------------
        NSUInteger serializedPolicyLength = [serializedPolicy length];
        [backingData appendData:[NSData dataWithBytes:&serializedPolicyLength length:sizeof(serializedPolicyLength)]];
        [backingData appendData:serializedPolicy];
        NSUInteger protectedContentLength = [MSCustomProtectedData getEncryptedContentLengthWithPolicy:policy contentLength:unprotectedData.length];
        [backingData appendData:[NSData dataWithBytes:&protectedContentLength length:sizeof(protectedContentLength)]];
    
        NSUInteger headerLength = sizeof(serializedPolicyLength) + serializedPolicyLength + sizeof(protectedContentLength);
    
        // Create the MSMutableCustomProtector used for encrypting content
        // The content start position is the current length of the backing data
        // The encryptedContentSize content size is 0 since there is no content yet
        [MSMutableCustomProtectedData customProtectorWithUserPolicy:policy
                                                    backingData:backingData
                                         protectedContentOffset:headerLength
                                                completionBlock:^(MSMutableCustomProtectedData *customProtector,
                                                                  NSError *error)
        {
            //Append data to the custom protector, this will encrypt the data and write it to the backing data
            [customProtector appendData:[contentToProtect dataUsingEncoding:NSUTF8StringEncoding] error:&error];
    
            //close the custom protector so it will flush and finalise encryption
            [customProtector close:&error];
    
        }];
      }
    

ComentáriosComments

Antes de inserir um comentário, pedimos-lhe que reveja as nossas Regras básicas.Before commenting, we ask that you review our House rules.