|
1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 /** |
|
17 @file MWspCOMethodInvoker.h |
|
18 @warning : This file contains Rose Model ID comments - please do not delete |
|
19 */ |
|
20 |
|
21 #ifndef __MWSPCOMETHODINVOKER_H__ |
|
22 #define __MWSPCOMETHODINVOKER_H__ |
|
23 |
|
24 // System includes |
|
25 #include <e32std.h> |
|
26 #include <stringpool.h> |
|
27 |
|
28 // Forward declarations |
|
29 class MWspCOMethodCallback; |
|
30 class MHTTPDataSupplier; |
|
31 class TUriC8; |
|
32 |
|
33 |
|
34 class MWspCOMethodInvoker |
|
35 /** |
|
36 @class MWspCOMethodInvoker |
|
37 @since 7.0 |
|
38 The MWspCOMethodInvoker and MWspCOMethodCallback form the API that provides |
|
39 the WSP Connection-Orientated Session Service Method Invocation facility, as |
|
40 described in the WSP Specification, July 2001. |
|
41 |
|
42 The MWspCOMethodInvoker interface is supplied by the Provider entity. The |
|
43 MWspCOMethodCallback interface is supplied by the Client entity. The Provider |
|
44 implements the communications necessary to send the primitives issued by the |
|
45 Client to the Server, and from the Server to the Client. |
|
46 |
|
47 A method transaction can only be invoked under the following circumstances; |
|
48 1) The WSP session is in either the Connecting, Connected or Resuming |
|
49 state. |
|
50 2) The number of of outstanding method transactions has not reached the |
|
51 negotiated Method MOR. |
|
52 Both these circumstances must be statisfied before a method may be invoked. |
|
53 |
|
54 Further, during the capability negotiations, the Protocol Option for Large |
|
55 Data Transfer may be refused (WSP Specification 8.3.2.3). If this is the case, |
|
56 then the use of the S-MethodInvokeData (by the Client) and S-MethodResultData |
|
57 (by the Server) is forbidden. |
|
58 |
|
59 The effect of not supporting LDT is that POST data may not be streamed and |
|
60 must not overflow the negotiated Server SDU size. The amount of allowed data |
|
61 in the S-MethodInvoke.req is dependent on the size of the destination URI |
|
62 and the method headers. A method transaction that exceeds the Server SDU size |
|
63 is aborted by the Client and is not invoked on the Provider. |
|
64 |
|
65 Another case in which the Client may abort a method transaction is when the |
|
66 negotiated Server Message size has been exceeded. This also applies when LDT |
|
67 is supported in the WSP session. The Client aborts the method invocation on |
|
68 the Provider as well. |
|
69 |
|
70 The object that encapsulates the concept of a method transaction implements |
|
71 the call-back API MWspCOMethodCallback. The Provider associates each of |
|
72 these objects with a Transaction Id used to distinguish between method |
|
73 transactions during a WSP session. |
|
74 @publishedAll |
|
75 @deprecated |
|
76 */ |
|
77 { |
|
78 public: // Methods |
|
79 |
|
80 /** @fn MethodInvokeReq(MWspCOMethodCallback& aMethodCallback, RStringF aMethod, const TUriC8& aRequestUri, const TDesC8& aRequestHeaders, const TDesC8& aRequestBody, TBool aMoreData) =0 |
|
81 Intended Usage : This represents the S-MethodInvoke.req primitive. The |
|
82 Provider initiates a method request, associating the |
|
83 parameter aMethodCallback with a Transaction Id for |
|
84 this request. This Id is unique for the lifetime of the |
|
85 transaction. |
|
86 |
|
87 The expected primitives to be received are S-MethodInvoke.cnf |
|
88 or S-MethodAbort.ind. The method is aborted if the Server |
|
89 Message size is exceeded. |
|
90 |
|
91 The aMoreData flag indicates whether there are subsequent |
|
92 S-MethodInvokeData primitives for this transaction. The |
|
93 data for entity body will not excced the SDU. |
|
94 @since 7.0 |
|
95 @param aMethodCallback A reference to an instance of the call- |
|
96 back API MWspCOMethodCallback. It |
|
97 uniquely identifies this method |
|
98 transaction for the lifetime of the |
|
99 transaction. |
|
100 @param aMethod An RStringF object that describes the |
|
101 HTTP method for this transaction. |
|
102 @param aRequestUri A URI object that specifies the resource |
|
103 to which this operation applies. |
|
104 @param aRequestHeaders A reference to a buffer with the encoded |
|
105 request headers. |
|
106 @param aRequestBody A reference to a buffer containing the |
|
107 data associated with the request. Only |
|
108 used if the method aMethod supports an |
|
109 entity body. |
|
110 @param aMoreData A boolean flag indicating whether there |
|
111 are subsequent S-MethodInvokeData |
|
112 primitives for this transaction. |
|
113 @pre The WSP session is in the Connecting, Connected or Resuming |
|
114 state. The method MOR has not been reached. The WSP method |
|
115 transaction is in Null state. |
|
116 @post The WSP method transaction is in Requesting state. Neither |
|
117 the Server SDU size nor the Server Message size have been |
|
118 exceeded. |
|
119 */ |
|
120 virtual void MethodInvokeReq( |
|
121 MWspCOMethodCallback& aMethodCallback, |
|
122 RStringF aMethod, |
|
123 const TUriC8& aRequestUri, |
|
124 const TDesC8& aRequestHeaders, |
|
125 const TDesC8& aRequestBody, |
|
126 TBool aMoreData |
|
127 ) =0; |
|
128 |
|
129 /** @fn MethodInvokeDataReq(MWspCOMethodCallback& aMethodCallback, const TDesC8& aRequestBody, const TDesC8& aTrailerHeaders, TBool aMoreData) =0 |
|
130 Intended Usage : This represents the S-MethodInvokeData.req primitive. |
|
131 The Provider sends more data associated with a |
|
132 previous S-MethodInvoke.req primitive. The Transport |
|
133 Handler uses the transaction callback to identify which |
|
134 previous S-MethodInvoke.req corresponds correctly. |
|
135 |
|
136 The aMoreData flag indicates whether there are subsequent |
|
137 S-MethodInvokeData primitives for this transaction. The |
|
138 data for entity body will not excced the SDU. |
|
139 |
|
140 If there are trailer headers these are provided by the |
|
141 input parameter aTrailerHeaders. This is only valid if |
|
142 this is the last S-MethodInvokeData primitive. |
|
143 |
|
144 The expected callback primitives that may follow are |
|
145 S-MethodInvokeData.cnf or S-MethodAbort.ind. The method |
|
146 is aborted if the negotiated Server Message size is |
|
147 exceeded. |
|
148 @since 7.0 |
|
149 @param aMethodCallback A reference to an instance of the call-back |
|
150 API MWspCOMethodCallback. It uniquely |
|
151 identifies this method transaction for the |
|
152 lifetime of the transaction. |
|
153 @param aRequestBody A reference to a buffer containing the data |
|
154 associated with the request. |
|
155 @param aTrailerHeaders A reference to a buffer with the encoded |
|
156 trailer headers. This must be empty unless |
|
157 this is the last S-MethodInvokeData |
|
158 primitive. |
|
159 @param aMoreData A boolean flag indicating whether there are |
|
160 subsequent S-MethodInvokeData primitives for |
|
161 this transaction. |
|
162 @pre The WSP method transaction is in the Requesting state. |
|
163 @post The WSP method transaction remains in the Requesting state. |
|
164 Neither the Server SDU size nor the Server Message size have |
|
165 been exceeded. |
|
166 */ |
|
167 virtual void MethodInvokeDataReq( |
|
168 MWspCOMethodCallback& aMethodCallback, |
|
169 const TDesC8& aRequestBody, |
|
170 const TDesC8& aTrailerHeaders, |
|
171 TBool aMoreData |
|
172 ) =0; |
|
173 |
|
174 /** @fn MethodAbortReq(MWspCOMethodCallback& aMethodCallback) =0 |
|
175 Intended Usage : This represents the S-MethodAbort.req primitive. The |
|
176 Provider aborts the method transaction specified by |
|
177 aMethodCallback. The Client expects the S-MethdoInvoke.ind |
|
178 primitive to indicate that the transaction is aborted. |
|
179 @since 7.0 |
|
180 @param aMethodCallback A reference to an instance of the call-back |
|
181 API MWspCOMethodCallback. It uniquely |
|
182 identifies this method transaction for the |
|
183 lifetime of the transaction. |
|
184 @pre The WSP method transaction is in any state other than the |
|
185 Null or Aborting state. |
|
186 @post The WSP method transaction is in the Aborting state. |
|
187 */ |
|
188 virtual void MethodAbortReq(MWspCOMethodCallback& aMethodCallback) =0; |
|
189 |
|
190 /** @fn MethodResultRes(MWspCOMethodCallback& aMethodCallback, const TDesC8& aAckHeaders) =0 |
|
191 Intended Usage : This represents the S-MethodResult.res primitive. The |
|
192 sending of acknowledgement headers is a negotiated |
|
193 capability. If the Server has not agreed to this |
|
194 capability, then the parameter aAckHeaders is ignored. |
|
195 @since 7.0 |
|
196 @param aMethodCallback A reference to an instance of the call-back |
|
197 API MWspCOMethodCallback. It uniquely |
|
198 identifies this method transaction for the |
|
199 lifetime of the transaction. |
|
200 @param aAckHeaders A buffer that contains the optional set of |
|
201 headers containing some information to return |
|
202 to the Server. This may be empty. |
|
203 @pre The WSP method transaction is in the Waiting2 or Completing |
|
204 state. |
|
205 @post If the WSP method transaction was in the Waiting2 state, it |
|
206 remains in that state. If the WSP method transaction was in |
|
207 the Completing state, it moves into the Null state and the |
|
208 method transaction is complete. |
|
209 */ |
|
210 virtual void MethodResultRes( |
|
211 MWspCOMethodCallback& aMethodCallback, |
|
212 const TDesC8& aAckHeaders |
|
213 ) =0; |
|
214 |
|
215 /** @fn MethodResultDataRes(MWspCOMethodCallback& aMethodCallback, const TDesC8& aAckHeaders) =0 |
|
216 Intended Usage : This represents the S-MethodResultData.res primitive. |
|
217 The sending of acknowledgement headers is a negotiated |
|
218 capability. If the Server has not agreed to this |
|
219 capability, then the parameter aAckHeaders is ignored. |
|
220 @since 7.0 |
|
221 @param aMethodCallback A reference to an instance of the call-back |
|
222 API MWspCOMethodCallback. It uniquely |
|
223 identifies this method transaction for the |
|
224 lifetime of the transaction. |
|
225 @param aAckHeaders A buffer that contains the optional set of |
|
226 headers containing some information to return |
|
227 to the Server. This may be empty. |
|
228 @pre The WSP method transaction is in the Waiting2 or Completing |
|
229 state. |
|
230 @post If the WSP method transaction was in the Waiting2 state, it |
|
231 remains in that state. If the WSP method transaction was in |
|
232 the Completing state, it moves into the Null state amd the |
|
233 method transaction is complete. |
|
234 */ |
|
235 virtual void MethodResultDataRes( |
|
236 MWspCOMethodCallback& aMethodCallback, |
|
237 const TDesC8& aAckHeaders |
|
238 ) =0; |
|
239 |
|
240 }; |
|
241 |
|
242 #endif // __MWSPCOMETHODINVOKER_H__ |
|
243 |