Creating an MTP Data Provider Plug-in

Before you start, you must:

MTP data providers are implemented as ECOM plug-ins loaded into the MTP framework. The MTP Data Provider APIs enable device creators to create data provider plug-ins and support specific media and data types. Data providers interact with the MTP framework using the API/SPI interface pair.

  1. Create a data provider plug-in class that derives from CMTPDataProviderPlugin and implements the abstract SPI methods defined by MMTPDataProvider.
  2. Call MMTPDataProviderFramework::DataCodeGenerator() to get a reference of MMTPDataCodeGenerator and generate a set of unique datacodes for a data provider service. Note: This step is only required to implement a data provider as a device service. Device creators can also write their own datacode allocation mechanism to avoid datacode conflicts. For more information about Datacodes, refer to the MTP Device Service Extension Specification. The MTP Device Services Extension Specification extends the MTP protocol. It moves the limited 16-bit datacodes to 128-bit Global Unique IDs (GUID) to support extensible operations, properties and formats for a service. For better performance and efficiency, 16-bit datacodes which map the GUIDs are still used. They are generated at run time on a device with unique values. Datacodes and their mapping GUIDs are sent to a host PC and then only datacodes are used in later communications. The MMTPDataCodeGenerator interface class defines the following functions:
    1. MMTPDataCodeGenerator::AllocateServiceID() generates a datacode for a service GUID.

    2. MMTPDataCodeGenerator::AllocateServicePropertyCode() generates datacodes for service property GUIDs.

    3. MMTPDataCodeGenerator::AllocateServiceFormatCode() generates datacodes service format GUIDs.

    4. MMTPDataCodeGenerator::AllocateServiceMethodFormatCode() generates datacodes for service method format GUIDs.

    The following code block shows how to generate datacodes for the Task service GUID and one of its service format GUIDs:
    void CMTPTaskDataProvider::ConstructL()
    {
    …
    
    //Get the reference of the Datacode Generator.
    MMTPDataCodeGenerator& datacodeGenerator(Framework().DataCodeGenerator());
    
    // Generate a datacode for the Windows task service GUID.
    TUint taskServiceID(0);
    const TMTPTypeUint128 KMTPTaskDpPersistentServiceID(
                              MAKE_TUINT64(0x10287013,0x00000001),
                              MAKE_TUINT64(0x00000000,0x00000000));
    User::LeaveIfError(datacodeGenerator.AllocateServiceID(
                                             KMTPTaskDpPersistentServiceID,
                                             0,
                                             taskServiceID));
    …
    
    //Generate a datacode for the service AbstractTask format.
    TUint16  abstractTaskFormatcode(0);
    const TMTPTypeUint128 KAbstractTaskGUID(
                               MAKE_TUINT64(0x522979c0,0x74cf44ab),
                               MAKE_TUINT64(0x975455bc,0x596a67df));
    User::LeaveIfError(datacodeGenerator.AllocateServiceFormatCode(
                                             KMTPTaskDpPersistentServiceID,
                                             KAbstractTaskGUID,
                                             abstractTaskFormatcode));
    …
    
    }
    
  3. Register and configure a data provider. Each Data Provider must register with the ECOM plug-in framework by creating and exporting a standard ECOM plug-in framework registration file. In addition, each MTP Data Provider is required to register itself with the MTP framework by exporting a compiled resource file as follows z:/resource/mtp/[implementation_uid].rsc Where [implementation_uid] is the Data Provider’s unique MTP Data Provider SPI implementation UID. For a Data Provider implemented as an ECOM plug-in [implementation_uid] should match the implementation_uid value specified in its ECOM plug-in registration file, for example z:/resource/mtp/[implementation_uid].rsc
  4. Notify USB cable disconnection. The MTP Data Provider must be notified by the Symbian MTP USB transport upon the USB disconnection from the Host. To notify the USB disconnection, the licensee must handle the EMTPDisconnected event using the ProcessNotificationL() function. For example,
    void CMTPImageDataProvider::ProcessNotificationL(TMTPNotification aNotification, const TAny* aParams)
    
        {
    
        __FLOG(_L8("ProcessNotificationL - Entry"));
    
        switch (aNotification)
    
            {
    
        case EMTPSessionClosed:
    
            SessionClosedL(*reinterpret_cast<const TMTPNotificationParamsSessionChange*>(aParams));
    
            break;
    
            
    
        case EMTPSessionOpened:
    
            SessionOpenedL(*reinterpret_cast<const TMTPNotificationParamsSessionChange*>(aParams));
    
            break;
    
        case EMTPDisconnected:
    
            {
    
            __FLOG(_L8("USB  - Disconnected"));   
    
            }
            
            break;
    
        default:
    
            // Ignore all other notifications.
    
            break;
    
            }
    
        __FLOG(_L8("ProcessNotificationL - Exit"));
    
        }
    
    
  5. Grant MTP Data Provider capabilities. The MTP daemon has the following capabilities. To be loaded by the MTP daemon, the same capabilities must be granted to your data provider plug-in.
    1. CommDD

    2. LocalServices

    3. NetworkControl

    4. NetworkServices

    5. PowerMgmt

    6. ReadDeviceData

    7. ReadUserData

    8. TrustedUI

    9. WriteDeviceData

    10. WriteUserData


  6. Set the file exclusion list and folder exclusion list Your data provider supports specific media and data type(s). You may need to prevent the File Data Provider and the Device Data Provider (and possibly any other Data Providers) from trying to handle the same data type(s). You can use the file exclusion list in the File Data Provider and the folder exclusion list in the Device Data Provider for this purpose. The ways to configure the lists are different based on whether your data provider is built in ROM or installed via SIS file.
    Option Description

    Data provider built in ROM

    For data providers included in the ROM.

    Data provider installed via SIS file

    For data providers installed via SIS file.

    Data provider built in ROM

    If the data provider is included in the ROM (z: drive), edit the configuration files directly as follows:


    1. Edit mtpfiledp_config.rss, the File Data Provider configuration resource file, using a text editor. Add the file format code to the format_exclusion_list section and add its mapping file extension to the extension_map section. For example a Music Data Provider is to be included in the ROM. The Music Data Provider supports .mp3, whose file format code is 0x3009. The mtpfiledp_config.rss file must be configured as follows:
      RESOURCE MTP_FILEDP_CONFIG fileConfig
      {
          enumeration_iteration_length = 32;
          format_exclusion_list = {
          //Association
          0x3001,
          0x3009 //mp3 code added to exclusion list, handled by Music Data Provider.
          };
          
          extension_map = 
          {
            ...
            MTP_FILEDP_EXTENSION_MAP // mp3 added to extension map, handled by Music Data Provider.
            {
            file_extension = "mp3";
            mtp_object_format = 0x3009;
            },
           
           ...
           };
      
      }

    2. Edit mtpdevicedp_config.rss, the Device Data Provider configuration resource file, using a text editor. Add the folder or drive to save the supported data to the folder_exclusion_list section, for example c:\media\music.
      RESOURCE MTP_DEVICEDP_CONFIG folderConfig
          {
          enumeration_iteration_length = 32;
          folder_exclusion_list = 
              {
              ...
      
              "c:\\media\\music\\",
              ...
      
              };
          }

    Data provider installed via SIS file

    If the data provider is installed via SIS file, MMTPDataProvider::Supported() and MMTPDataProvider::SupportedL() must be implemented for the folder and file exclusion lists.

    For example after a phone is shipped, the Music Data Provider can be installed via SIS files to the phone. The Music Data Provider supports .mp3, whose file format code is 0x3009. MP3 files are saved under c:\media\music. The following snippet of code shows an implementation of the two methods.

    /**
    define all the operations that are supported by the music data provider
    */
    static const TUint16 KMTPMusicDpSupportedFormats[] =
        {
        EMTPFormatCodeWMA,
        EMTPFormatCodeMP3
        };
    
    ...
    
    void CMTPMusicDataProvider::Supported(TMTPSupportCategory aCategory, RArray<TUint>& aArray) const
        {
        switch (aCategory) 
            {      
        case EObjectCaptureFormats:
        case EObjectPlaybackFormats:
               {
               TInt count = sizeof(KMTPMusicDpSupportedFormats) / sizeof(TUint16);
               for(TInt i = 0; i < count; i++)
                    {
                    aArray.Append(KMTPMusicDpSupportedFormats[i]);
                    }
            }
            break;
                         
        default:
            break;
            }
        }
    
    void CMTPMusicDataProvider::SupportedL(TMTPSupportCategory aCategory, CDesCArray& aStrings) const
        {
        switch (aCategory) 
            {
        case EFolderExclusionSets:
             {
             //Hardcoded path, can be read from a resource file.
             _LIT(KMusicDPRootDir, "c:\\media\\music\\*");
             aStrings.AppendL(KMusicDPRootDir);
              }
              break;
        case EFormatExtensionSets:
             {
             _LIT(KFormatExtensionMP3, "0x3009:MP3");
             aStrings.AppendL(KFormatExtensionMP3);
             }
             break;
        
        default:
             break;
            }
        }
    ...