|
1 /* |
|
2 * Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Hostlet call back interface |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef M_SEN_HOSTLET_H |
|
20 #define M_SEN_HOSTLET_H |
|
21 |
|
22 // INCLUDES |
|
23 #include <e32base.h> // for CBase |
|
24 #include <badesca.h> |
|
25 |
|
26 #include <MSenHostletRequest.h> |
|
27 #include <MSenHostletResponse.h> |
|
28 #include <SenXmlServiceDescription.h> |
|
29 #include <SenServiceConnection.h> |
|
30 |
|
31 // FORWARD DECLARE |
|
32 |
|
33 // CLASS DECLARATION |
|
34 class MSenHostlet |
|
35 { |
|
36 public: |
|
37 /** |
|
38 * Main method for receiving incoming messages, which are typically SOAP / XML, |
|
39 * and for providing service for these requests. |
|
40 * @param aRequestUtf8 the request that needs to be be processed by the |
|
41 * hostlet application (local service provider). |
|
42 * @param aResponse is where response data is to be set. |
|
43 * CSenHostletConnection::ResponsdL should be called |
|
44 * in order to send the response back to the requester |
|
45 * (service consumer). |
|
46 */ |
|
47 virtual TInt ServiceL(MSenHostletRequest& aRequest, MSenHostletResponse& aResponse) = 0; |
|
48 |
|
49 /** |
|
50 * Defines the service endpoint for this hostlet |
|
51 * @return endpoint that this hostlet has specified. If hostlet |
|
52 * implementation does not wish to define any endpoint, but to |
|
53 * use contract only, it should return KNullDesC8 (zero-length descriptor). |
|
54 * In such case, CSenHostletConnection constructor will attempt to resolve |
|
55 * secure identifier (UID3) of the application, and use that to generate |
|
56 * a locally unique endpoint. If the UID3 is not available, then the |
|
57 * constructor of CSenHostletConnection will leave with the following |
|
58 * error code: KErrSenNoContractNoEndPoint |
|
59 * |
|
60 * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot |
|
61 * create hostlet connection: instead, CSenHostletConnection constructor |
|
62 * will leave with the following code: KErrSenNoContractNoEndPoint |
|
63 * |
|
64 * If endpoint is not specified, hostlet connection itself |
|
65 * will generate an endpoint from applications secure ID (UID3) if such is available, |
|
66 * and consumers can invoke the service via the provided contract ("service type" |
|
67 * identifier). |
|
68 * |
|
69 */ |
|
70 virtual TPtrC8 Endpoint() const = 0; |
|
71 |
|
72 /** |
|
73 * Defines the service constract URI for this hostlet |
|
74 * @return the URI identifier for the provided service, for example |
|
75 * "urn:liberty:id-sis-pp:2003-08". Note that there might be multiple |
|
76 * hostlets (local service providers) which all share common service |
|
77 * type, that is, they all have same service contract URI. |
|
78 * |
|
79 * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot |
|
80 * create hostlet connection: instead, CSenHostletConnection constructor |
|
81 * will leave with the following error code: KErrSenNoContractNoEndPoint |
|
82 */ |
|
83 virtual TPtrC8 Contract() const = 0; |
|
84 |
|
85 /** |
|
86 * Defines the framework for this hostlet. |
|
87 * @return the framework ID. Default inline implementation |
|
88 * returns RESTful service invocation framework ID, |
|
89 * KDefaultRestServicesFrameworkID, as defined in SenServiceConnection.h |
|
90 */ |
|
91 inline virtual TPtrC8 FrameworkId() const { return KDefaultRestServicesFrameworkID(); } |
|
92 |
|
93 /** |
|
94 * Each Hostlet implementation may further describes its service via this callback. |
|
95 * @param aSD is the description, where service specific attributes can be defined. |
|
96 * Default, inline implementation sets the endpoint, contract and framework ID |
|
97 * by calling the other, more simple callbacks. |
|
98 * |
|
99 * It is mandatory for each hostlet to define either endpoint or contract. |
|
100 * Otherwise, the constuctor of CSenHostletConnection will leave with the |
|
101 * following error code: |
|
102 * KErrSenNoContractNoEndPoint - neither endpoint or contract was |
|
103 * specified. This is illegal, since the service would lack an identifier. |
|
104 * |
|
105 * @param aSD is the service description into which this hostlet may further |
|
106 * define other service specific information, like facets. Note that this |
|
107 * call back is "stronger" than Endpoint() and Contract(), and thus any |
|
108 * value specified in this method will be in effect for the hostlet connection. |
|
109 */ |
|
110 inline virtual void DescribeServiceL(CSenXmlServiceDescription& aSD) |
|
111 { |
|
112 aSD.SetEndPointL(Endpoint()); |
|
113 aSD.SetContractL(Contract()); |
|
114 aSD.SetFrameworkIdL(FrameworkId()); |
|
115 } |
|
116 |
|
117 /** |
|
118 * This callback function is invoked each time when any hostlet connection's |
|
119 * asynchronous RespondL is completed. Method can be used to trigger the |
|
120 * release of some response releated system resources, as it is invoked |
|
121 * after the response has been delivered to the consumer (application |
|
122 * may wish to close handles to reserved file or memory). |
|
123 * |
|
124 * @param aTxnId identifies what transaction (service message) was completed |
|
125 * @param aCompletionCode indicates whether transaction completed ok (KErrNone) |
|
126 * or not (error code). |
|
127 * @param aDesc may provide additional information about completed transaction, |
|
128 * typically this description is provided, if an error has occured. |
|
129 * It is optional for hostlet implementation to implement this method. |
|
130 */ |
|
131 inline virtual void OnServiceCompleteL(TInt /* aTxnId */, |
|
132 TInt /* aCompletionCode */, |
|
133 const TDesC8& /* aDesc*/ ) { ; } |
|
134 |
|
135 /** |
|
136 * Hostlet connection calls this method several times, passing a different |
|
137 * UID per each call. If application wants to provide particular interface |
|
138 * to hostlet connection (web services stack), it needs to return a pointer |
|
139 * to such M-class as a return value of this method. For any interface, that |
|
140 * application has not implemented, it is supposed to return NULL. |
|
141 * @param aUID is the unique identifier of some interface |
|
142 * @return value should be a valid (void) pointer to any interface implemented |
|
143 * by the application. NULL signalizes that application does not provide interface |
|
144 * for give UID. |
|
145 */ |
|
146 inline virtual TAny* GetInterfaceByUid( TUid /* aUID */ ) { return NULL; }; |
|
147 }; |
|
148 |
|
149 |
|
150 #endif // M_SEN_HOSTLET_H |
|
151 |
|
152 // End of File |