|
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-FF410602-8408-555E-B918-C0CF484535E7" xml:lang="en"><title>Writing |
|
13 Interface Definitions</title><abstract><p>To use a plug-in, the client of the plug-in framework needs to |
|
14 instantiate an object through the interface definition, use the object and |
|
15 delete the object when the scope of the object usage is complete. Client calls |
|
16 to the interface definition for construction and destruction translate directly |
|
17 through REComSession into loading and unloading of the correct implementation. </p><p>The <xref href="GUID-9E0CBB66-A573-5BBE-9788-95B313325C7E.dita">interface definition</xref> defines |
|
18 functions that offer services to the clients and enable object instantiation. |
|
19 The object instantiation functions uses the plug-in framework to create an |
|
20 instance of an appropriate implementation, and returns the instance to the |
|
21 client. </p></abstract><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
22 <context><p>A function in the interface definition delegates the object instantiation |
|
23 to a static function <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-C7F147AC-6D77-3169-AAB4-B27262B4333B"><apiname>REComSession::CreateImplementationL()</apiname></xref> . |
|
24 The <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-C7F147AC-6D77-3169-AAB4-B27262B4333B"><apiname>REComSession::CreateImplementationL()</apiname></xref> is an overloaded |
|
25 function and offers many input parameter options. The appropriate <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-C7F147AC-6D77-3169-AAB4-B27262B4333B"><apiname>REComSession::CreateImplementationL()</apiname></xref> function |
|
26 is called for object instantiation. If the client passes input data then this |
|
27 data must be wrapped in a <codeph>TEComResolverParams</codeph> object. </p> <p> </p> </context> |
|
28 <steps id="GUID-B502261A-48DA-5EC1-82F9-6136CF5A2C50"> |
|
29 <step id="GUID-D9F104A5-4D58-5488-AB0A-C90C26A40C28"><cmd>Derive an interface |
|
30 definition class from <xref href="GUID-8F6FE089-E2A8-30F4-B67E-10F286347681.dita"><apiname>CBase</apiname></xref> or <xref href="GUID-727D2B62-09A9-3CBC-AB6F-591E52EC68EB.dita"><apiname>RHandleBase</apiname></xref> based |
|
31 class. The class must always declare a private UID member. </cmd> |
|
32 <info>The following shows an example segment of an interface definition class |
|
33 that derives from CActive. </info> |
|
34 <stepxmp><codeblock id="GUID-2D4E24B1-0463-5970-B0FD-321FC599E1CB" xml:space="preserve">class CExampleInterfaceDefinition : public CActive |
|
35 { |
|
36 public: |
|
37 // Wraps ECom object instantiation |
|
38 static CExampleInterfaceDefinition* NewL(); |
|
39 static CExampleInterfaceDefinition* NewL(const TDesC& aMatchString); |
|
40 // Wraps ECom object destruction |
|
41 virtual ~CExampleInterfaceDefinition(); |
|
42 // Interface service |
|
43 virtual void DoMethodL() = 0; |
|
44 ... |
|
45 private: |
|
46 // Instance identifier key or UID. |
|
47 TUid iDtor_ID_Key; |
|
48 };</codeblock> </stepxmp> |
|
49 </step> |
|
50 <step id="GUID-82F4FEE2-22B9-51E7-96CD-2CAA7FBF78C2"><cmd>Implement the object |
|
51 creation function NewL() for the derived class. </cmd> |
|
52 <info>Call the appropriate <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-C7F147AC-6D77-3169-AAB4-B27262B4333B"><apiname>REComSession::CreateImplementationL()</apiname></xref> function |
|
53 if the implementation is to receive data from the client. </info> |
|
54 <stepxmp><codeblock id="GUID-4447C35F-1001-57FB-941F-441E0A2C4799" xml:space="preserve"> // The NewL() function accepts client resolution string as input |
|
55 inline CExampleInterfaceDefinition* CExampleInterfaceDefinition::NewL(const TDesC& aMatchString) |
|
56 { |
|
57 const TUid KExampleInterfaceDefinitionUid = {0x10009DC0}; |
|
58 // The client resolution string is wrapped in TEComResolverParams object for resolution. |
|
59 TEComResolverParams resolverParams; |
|
60 resolverParams.SetDataType(aMatchString); |
|
61 TAny* ptr = REComSession::CreateImplementationL( |
|
62 KExampleInterfaceDefinitionUid, |
|
63 _FOFF(CExampleInterfaceDefinition,iDtor_ID_Key), |
|
64 resolverParams); |
|
65 |
|
66 return REINTERPRET_CAST <CExampleInterfaceDefinition*>(ptr); |
|
67 }</codeblock> </stepxmp> |
|
68 <stepxmp><codeblock id="GUID-7F634037-2D79-53E0-B132-B9E963603B69" xml:space="preserve"/></stepxmp> |
|
69 </step> |
|
70 </steps> |
|
71 <postreq><p>The interface definition needs to define a destructor function |
|
72 to destroy the object after use. The interface destructor notifies the plug-in |
|
73 framework about the object destruction. </p> <p>The destructor of the interface |
|
74 definition must call the static function <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-8BA69111-0451-34CA-A1E8-C83513C4D29D"><apiname>REComSession::DestroyedImplementation()</apiname></xref> to |
|
75 signal the object destruction to plug-in framework. The instance identifier |
|
76 key is passed as a input parameter to <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-8BA69111-0451-34CA-A1E8-C83513C4D29D"><apiname>REComSession::DestroyedImplementation()</apiname></xref> to |
|
77 identify the instance. </p> <codeblock id="GUID-1E935BFD-D485-5F4D-9569-D34FEC1D90DC" xml:space="preserve">inline CExampleInterfaceDefinition::~CExampleInterfaceDefinition() |
|
78 { |
|
79 REComSession::DestroyedImplementation(iDtor_ID_Key); |
|
80 }</codeblock> <p> <b>Note</b>: The memory clean-up function<xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-1AACEF53-2CAD-34EC-A485-CE49BC8B9BD8"><apiname>REComSession::FinalClose()</apiname></xref> should |
|
81 not be invoked inside the destructor, or elsewhere in the interface. For more |
|
82 details refer the topic <xref href="GUID-E3A80D62-09A5-502D-AB55-6AB2A5623465.dita">Cleaning-up |
|
83 Memory</xref>. </p> </postreq> |
|
84 </taskbody></task> |