|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-3FF0F248-EDF0-5348-BC43-869CE1B5B415" xml:lang="en"><title>Setting |
|
13 Microsoft OS Descriptor</title><shortdesc>This section describes how to set the Microsoft OS Descriptor (MOD) |
|
14 for using Symbian MTP over USB services. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
15 <prereq><p>Before you start, you must: </p> <ul> |
|
16 <li id="GUID-9A2A0DD6-06B3-5BF9-966F-B2E83C1CB18A"><p>Have a general understanding |
|
17 of the <xref href="http://www.microsoft.com" scope="external">MTP Enhanced |
|
18 Specification v0.95</xref>. </p> </li> |
|
19 <li id="GUID-2E60F217-425C-593C-8D35-D7D82F842D8D"><p>Have a general understanding |
|
20 of the <xref href="http://www.usb.org/developers/devclass/" scope="external">USB |
|
21 2.0 Specification</xref> (particularly Chapter 9.3 which describes the request |
|
22 types). </p> </li> |
|
23 <li id="GUID-A4BE2E18-013B-5FF9-A126-961EBB73ACDE"><p>Understand <xref href="http://msdn.microsoft.com/en-us/library/ms790473.aspx" scope="external">Microsoft-Defined USB Descriptors</xref>, <xref href="http://www.microsoft.com/whdc/connect/usb/os_desc.mspx" scope="external">Microsoft OS Descriptors</xref> and <xref href="http://msdn.microsoft.com/en-us/library/ms790473.aspx" scope="external">Extended Compat ID OS Feature Descriptor Specification</xref> in |
|
24 detail. </p> </li> |
|
25 <li id="GUID-DDB32234-882D-522C-8D60-9F80FCF7DF31"><p>Understand the <xref href="GUID-B2F5537B-3F47-5172-8DFA-185CC1CAAD22.dita">Symbian MTP over USB architecture</xref>. </p> </li> |
|
26 </ul> </prereq> |
|
27 <context><p>The USB Device Working Group does not define the class and sub-class |
|
28 ID for MTP. To allow a Symbian device to plug into Windows and handle MTP |
|
29 requests without installing software or requiring user interactions, device |
|
30 creators must provide Microsoft OS Descriptor (MOD) support in their user |
|
31 implementations. </p> <p>Two MODs must be supplied by the Symbian device: |
|
32 The OS string descriptor which stores vendor-specific information and the |
|
33 OS feature descriptor which contains the compatible ID (compat ID) and MTP |
|
34 sub-compatible ID (sub-compat ID). The compat ID is the class code for MTP. |
|
35 After getting a valid OS string descriptor, Windows will try to get the compat |
|
36 ID for MTP. The driver or class for MTP is finally loaded on Windows to handle |
|
37 MTP requests. </p> <p>To enable Symbian MTP over USB, device creators must |
|
38 implement a MOD solution. The implementation is referred to as user implementation. |
|
39 The implementation can be built into a user binary such as EXE or DLL. The |
|
40 user binary must be started up or loaded any time before enabling the MTP |
|
41 over USB. </p> <p>The following tasks must be completed in the user implementation: </p> <ol id="GUID-12B79044-A50F-5C51-A6E3-1B4358683B58"> |
|
42 <li id="GUID-33C846CF-93A5-582E-A208-00B2B4B8D815"><p>Load the USB Logical |
|
43 Device Driver (LDD) and open an LDD client. </p> <p>After the user binary |
|
44 is loaded, the LDD must be loaded and the LDD client must be opened. The string |
|
45 OS descriptor can then be written into the LDD in the next step. </p> </li> |
|
46 <li id="GUID-B6FEFA9E-98AC-5AFF-ABE2-50FB8E9BCB25"><p>Set the OS string descriptor |
|
47 to the LDD. </p> <p>A USB device which supports MOD must contain an OS string |
|
48 descriptor. Windows sends a request to the device to retrieve the OS string |
|
49 descriptor from the LDD. </p> </li> |
|
50 <li id="GUID-5776F91A-6279-57F7-B257-2DCA9563B190"><p>Route device-directed |
|
51 requests to the user binary. </p> <p>In the next step, Windows will send a |
|
52 control request to the device to get the compat ID OS feature descriptor. |
|
53 This request is vendor-specific and device-directed and must be handled by |
|
54 device creators in their user implementation. To enable the USB Stack to route |
|
55 the request to the user binary, the user implementation must call <codeph>RDevUsbcClient::SetDeviceControl()</codeph>. |
|
56 Device-directed requests from the PC are all then routed to this instance |
|
57 of <codeph>RDevUsbcClient</codeph>. </p> <fig id="GUID-FD68DA9C-2175-5B9D-B4A1-8A8B6D0EAEA8"> |
|
58 <image href="GUID-1E2DC905-472F-519F-A390-A1189FCB0F9D_d0e602075_href.jpg" placement="inline"/> |
|
59 </fig> </li> |
|
60 <li id="GUID-39D9E728-14DA-58DB-9F3A-C30B23832ECA"><p>Provide an OS feature |
|
61 descriptor handler. </p> <p>Once a valid OS string descriptor is returned, |
|
62 Windows sends another control request to get the Microsoft extended compat |
|
63 ID OS feature descriptor. </p> <p>Once the compat ID has been returned to |
|
64 the PC it can load the right MTP driver and class to handle MTP requests. </p> <p>Note: |
|
65 The string OS descriptor is written into the LDD. The OS feature descriptor |
|
66 is returned by the user implementation at runtime. </p> </li> |
|
67 </ol> <p>For more information about device directed requests and other types |
|
68 of requests, refer to <xref href="http://www.usb.org/developers/devclass/" scope="external">USB 2.0 Specification Chapter 9.3</xref>. For more information |
|
69 about the OS string descriptor and OS feature descriptor, refer to <xref href="http://www.microsoft.com/whdc/connect/usb/os_desc.mspx" scope="external">Microsoft OS Descriptors</xref>. </p> </context> |
|
70 <steps id="GUID-DA0DA5E7-D1CA-59DA-AAA3-4C6B05E1A0D9"> |
|
71 <step id="GUID-03B9EE7D-F04A-5957-8B68-6319BE685586"><cmd/> |
|
72 <info>Load the USB LDD–<filepath>usbc.ldd</filepath> and open a client of |
|
73 it. </info> |
|
74 <stepxmp><codeblock id="GUID-799C6FC1-438A-5B7D-857B-02E58C29E3CB" xml:space="preserve">_LIT(KUsbLDDName, "eusbc"); //Name passed to User::LoadLogicalDevice() |
|
75 _LIT(KUsbLDDFreeName, "Usbc"); //Name passed to User::FreeLogicalDevice() |
|
76 |
|
77 TInt err = User::LoadLogicalDevice(KUsbLDDName); // Load the USB logical device |
|
78 |
|
79 if (err != KErrNone && err != KErrAlreadyExists) |
|
80 { |
|
81 User::Leave(err); |
|
82 } |
|
83 |
|
84 RDevUsbcClient ldd; //Create a client of the USB logical device |
|
85 |
|
86 User::LeaveIfError(ldd.Open(0)); //Open the client |
|
87 |
|
88 </codeblock> </stepxmp> |
|
89 </step> |
|
90 <step id="GUID-8C094EE4-5C2D-54F6-A62F-9197B66CC606"><cmd/> |
|
91 <info>Set the OS string descriptor. </info> |
|
92 <info>OS string descriptor is stored in the USB device driver at the fixed |
|
93 index of 0xEE. It contains a request number that Windows uses to retrieve |
|
94 OS feature descriptors. </info> |
|
95 <stepxmp><codeblock id="GUID-5B8B2191-F298-578F-AB9D-417CE44CA4D3" xml:space="preserve">/** |
|
96 * MTP OS string decsriptor definitions. |
|
97 */ |
|
98 const TUint8 KMTPUsbOSStringIndex(0xEE); //OS string descriptor index |
|
99 _LIT16(KMTPUsbOSStringSignature, "MSFT100\xAE"); //qwSignature and bMS_VendorCode |
|
100 |
|
101 // Write the OS string descriptor to the LDD. |
|
102 User::LeaveIfError(ldd.SetStringDescriptor(KMTPUsbOSStringIndex, KMTPUsbOSStringSignature)); |
|
103 |
|
104 </codeblock> </stepxmp> |
|
105 <info> <codeph>qwSignature</codeph> and <codeph>bMS_VendorCode</codeph> are |
|
106 two key fields which must be set. <codeph>qwSignature</codeph> is a Unicode |
|
107 character array which identifies the descriptor as an OS string descriptor. <codeph>bMS_VendorCode</codeph> is |
|
108 one byte field whose value is set by the vendor. This value is used by Windows |
|
109 to request the OS feature descriptor (compat ID and sub-compat ID). </info> |
|
110 </step> |
|
111 <step id="GUID-6F5FD06E-53FC-556D-AB22-FB5DADBFE60A"><cmd/> |
|
112 <info>Route device-directed requests to the user binary. </info> |
|
113 <info>The user implementation must include the following to enable the USB |
|
114 Stack to route the device directed requests to the user binary. </info> |
|
115 <stepxmp><codeblock id="GUID-44E8D26E-0D0F-5643-8483-5E1F3CA4C7F8" xml:space="preserve">User::LeaveIfError(ldd.SetDeviceControl()); |
|
116 </codeblock> </stepxmp> |
|
117 <info> Note: Only one instance of RDevUsbcClient can hold the device control |
|
118 at any given time. </info> |
|
119 </step> |
|
120 <step id="GUID-34F47BD0-9489-5534-A207-ABCC9D689B1F"><cmd/> |
|
121 <info>Provide the OS feature descriptor handler. </info> |
|
122 <info>Once a valid OS string descriptor has been returned, Windows retrieves |
|
123 the OS feature descriptor which it uses to load the appropriate USB driver. |
|
124 In this case, the OS feature descriptor contains the MTP compat ID and MTP |
|
125 sub-compat ID. </info> |
|
126 <stepxmp><codeblock id="GUID-A1CEEFCB-CEFE-5A55-9B86-9B6833020B9B" xml:space="preserve">// KMsOSFeatureDescriptor |
|
127 _LIT8(KMsOSFeatureDescriptor, "\x28\x00\x00\x00\x00\x01\x04\x00\x01\x00\x00\x00\x00\x00\x00\x00" \ |
|
128 //dwLength | bcdVersion | wIndex | bCount | Reserved |
|
129 //4 characters | 2 chars | 2 | 1 | 7 |
|
130 |
|
131 "\x00\x01\x4D\x54\x50\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"); |
|
132 // bFirstInterfaceNumber | bInterfaceCount |compatibleID | subCompatibleID | Reserved |
|
133 // 1 | 1 | 8 | 8 | 6 |
|
134 |
|
135 const TInt KMODHeaderSize = 0x10; //The first 16 characters of the feature descriptor |
|
136 const TInt KMODFunctionSize = 0x28; |
|
137 |
|
138 TRequestStatus status; |
|
139 |
|
140 //aRequest is a structure for requests defined by a device creator |
|
141 //wLength is the field which specifies the length of the data to be transferred |
|
142 TInt length(aRequest.wLength); |
|
143 |
|
144 if (length == KMODHeaderSize) |
|
145 { |
|
146 // The request is for the header. Return just the header |
|
147 ldd.Write(status, EEndpoint0, KMsOSFeatureDescriptor().Left(KMODHeaderSize), KMODHeaderSize, ETrue); |
|
148 } |
|
149 else if (length == KMODFunctionSize) |
|
150 { |
|
151 ldd.Write(status, EEndpoint0, KMsOSFeatureDescriptor(),KMODFunctionSize, ETrue); |
|
152 }</codeblock> </stepxmp> |
|
153 </step> |
|
154 </steps> |
|
155 </taskbody><related-links> |
|
156 <link href="GUID-B2F5537B-3F47-5172-8DFA-185CC1CAAD22.dita"><linktext>MTP USB Transport |
|
157 Overview</linktext></link> |
|
158 <link href="GUID-DE2E64A5-417A-538C-904B-6D498BB55273.dita"><linktext>Symbian USB |
|
159 Manager</linktext></link> |
|
160 </related-links></task> |