iOS/OS X kodu örnekleriiOS/OS X code examples

Bu konuda, RMS SDK’in iOS/OS X sürümü için önemli kod öğeleri sunulacaktır.This topic will introduce you to important code elements for the iOS/OS X version of the RMS SDK.

Not Örnek kodda ve ardından gelen açıklamalarda, istemci işlemini belirtmek üzere MSIPC (Microsoft Bilgi Koruması ve Denetimi) kullanıyoruz.Note In the example code and descriptions that follow, we use the term MSIPC (Microsoft Information Protection and Control) to reference the client process.

Microsoft Rights Management SDK 4.2’yi kullanma - önemli senaryolarUsing the Microsoft Rights Management SDK 4.2 - key scenarios

Aşağıda, bu SDK’ya alışmanız için önemli geliştirme senaryolarını temsil eden daha büyük bir örnek uygulamadan Objective C kodu örnekleri verilmiştir.Following are Objective C code examples from a larger sample application representing development scenarios important to your orientation to this SDK. Bunlar, korumalı olarak belirtilen Microsoft Korumalı Dosya biçimi kullanılmasını, özel korumalı dosya biçimleri kullanımını ve özel UI denetimlerinin kullanımını göstermektedir.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.

Senaryo: Bir RMS korumalı dosya kullanmaScenario: Consume an RMS protected file

  • 1. adım: Oluşturma bir MSProtectedData nesnesiStep 1: Create an MSProtectedData object

    Açıklama: Örneği bir MSProtectedData nesnesi kendi kullanarak hizmet kimlik doğrulaması uygulayan oluşturma yöntemiyle MSAuthenticationCallback örneğinigeçirerekbirbelirteçalmakiçinMSAuthenticationCallback, parametre olarak Msprotecteddata, MSIPC API.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. Aşağıdaki örnek kod bölümünde yer alan MSProtectedData protectedDataWithProtectedFile çağrısına bakın.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];
          }];
      }
    
  • 2. adım: Active Directory Authentication Library (ADAL) kullanarak kurulum kimlik doğrulaması.Step 2: Setup authentication using the Active Directory Authentication Library (ADAL).

    Açıklama: Bu adımda uygulamak için kullanılan ADAL göreceğiniz bir MSAuthenticationCallback örnek kimlik doğrulama parametreleriyle.Description: In this step you will see ADAL used to implement an MSAuthenticationCallback with example authentication parameters. ADAL kullanımı hakkında daha fazla bilgi için, bkz. 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);
                            }
                        }];
     }
    
  • 3. adım: Bu kullanıcı bu içerikle düzenleme hakkının mevcut olup olmadığını denetleyin MSUserPolicy accessCheck yöntemi bir MSUserPolicy nesne.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;
        }
    }
    

Senaryo: Şablon kullanarak yeni bir korumalı dosya oluşturmaScenario: Create a new protected file using a template

Bu senaryo, bir şablonlar listesi MSTemplateDescriptor alma, birincisi seçilip bir ilke oluşturma, sonra yeni korumalı dosya oluşturma ve bu dosyaya yazmayla başlar.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.

  • 1. adım: Şablonları listesini alınStep 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)
                               }];
    }
    
  • 2. adım: Oluşturma bir MSUserPolicy listedeki birinci şablonu kullanarak.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)
        }];
    }
    
  • 3. adım: Oluşturma bir MSMutableProtectedData ve ona içerik yazın.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)
        }];
    }
    

Senaryo: Özel bir korumalı dosyayı açmaScenario: Open a custom protected file

  • 1. adım: Oluşturma bir MSUserPolicy gelen bir 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)
        {
    
        }];
     }
    
  • 2. adım: Oluşturma bir MSCustomProtectedData kullanarak MSUserPolicy gelen 1. adım ve ondan okuyun.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);
        }];
     }
    

Senaryo: Bir özel (geçici) ilkeyi kullanarak özel bir korumalı dosya oluşturmaScenario: Create a custom protected file using a custom (ad-hoc) policy

  • 1. adım: Kullanıcı tarafından sağlanan bir e-posta adresiyle bir ilke tanımlayıcısı oluşturun.Step 1: With an email address provided by the user, create a policy descriptor.

    Açıklama: Uygulamada cihaz arabiriminden kullanıcı girişleri kullanılarak aşağıdaki nesneleri oluşturmanız; MSUserRights ve 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;
    }
    
  • 2. adım: Bir özel Oluştur MSUserPolicy ilke tanımlayıcısı 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)
        }];
    }
    
  • 3. adım: İçerik oluşturup MSMutableCustomProtectedData ve kapatın.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];
    
        }];
      }