diff -r ebc84c812384 -r 46218c8b8afa Symbian3/PDK/Source/GUID-DB82D140-AB1B-5AA9-89CB-A5F68F328C85.dita --- a/Symbian3/PDK/Source/GUID-DB82D140-AB1B-5AA9-89CB-A5F68F328C85.dita Thu Mar 11 15:24:26 2010 +0000 +++ b/Symbian3/PDK/Source/GUID-DB82D140-AB1B-5AA9-89CB-A5F68F328C85.dita Thu Mar 11 18:02:22 2010 +0000 @@ -1,319 +1,319 @@ - - - - - -Creating -an MTP Data Provider Plug-in -

Before you start, -you must:

    -

  • Understand the MTP Data -Provider API.

    • -

  • Understand Symbian -capabilities.

    • -

  • MTP Device Services Extension Specification.

    • -
 -

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.

- -Create a data provider -plug-in class that derives from CMTPDataProviderPlugin and -implements the abstract SPI methods defined by MMTPDataProvider. - -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. -

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

    3. -

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

    4. -

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

    5. -
 -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)); -… - -} - - -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 - -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")); - - } - - - -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. -

  2. LocalServices

    3. -

  3. NetworkControl

    4. -

  4. NetworkServices

    5. -

  5. PowerMgmt

    6. -

  6. ReadDeviceData

    7. -

  7. ReadUserData

    8. -

  8. TrustedUI

    9. -

  9. WriteDeviceData

    10. -

  10. WriteUserData

    11. -
 - - -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. - - -

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:

- - -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; - }, - - ... - }; - -} - - -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; - } - } -... - - - - + + + + + +Creating +an MTP Data Provider Plug-in +

Before you start, +you must:

    +

  • Understand the MTP Data +Provider API.

    • +

  • Understand Symbian +capabilities.

    • +

  • MTP Device Services Extension Specification.

    • +
 +

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.

+ +Create a data provider +plug-in class that derives from CMTPDataProviderPlugin and +implements the abstract SPI methods defined by MMTPDataProvider. + +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. +

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

    3. +

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

    4. +

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

    5. +
 +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)); +… + +} + + +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 + +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")); + + } + + + +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. +

  2. LocalServices

    3. +

  3. NetworkControl

    4. +

  4. NetworkServices

    5. +

  5. PowerMgmt

    6. +

  6. ReadDeviceData

    7. +

  7. ReadUserData

    8. +

  8. TrustedUI

    9. +

  9. WriteDeviceData

    10. +

  10. WriteUserData

    11. +
 + + +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. + + +

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:

+ + +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; + }, + + ... + }; + +} + + +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; + } + } +... + + + + \ No newline at end of file