2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FNetHttpHttpTransaction.h
20 * @brief This is the header file for the %HttpTransaction class.
22 * This header file contains the declarations of the %HttpTransaction class.
25 #ifndef _FNET_HTTP_HTTP_TRANSACTION_H_
26 #define _FNET_HTTP_HTTP_TRANSACTION_H_
28 #include <FNetHttpHttpTypes.h>
29 #include <FNetHttpHttpRequest.h>
30 #include <FNetHttpHttpResponse.h>
31 #include <FNetHttpHttpAuthentication.h>
32 #include <FNetHttpIHttpTransactionEventListener.h>
33 #include <FNetHttpIHttpEntity.h>
34 #include <FNetHttpIHttpProgressEventListener.h>
36 namespace Tizen { namespace Net { namespace Http
38 class _HttpTransactionImpl;
40 * @class HttpTransaction
41 * @brief This class manages the HTTP transaction that encapsulates a request and a response.
45 * The %HttpTransaction class manages the HTTP transaction that encapsulates a request and a response.
46 * A transaction represents an interaction between the HTTP client and the HTTP origin server.
48 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/http_transaction.htm">HTTP Transaction</a>.
50 * The following example demonstrates how to use the %HttpTransaction class.
57 using namespace Tizen::Base;
58 using namespace Tizen::Net::Http;
61 TestHttpTransaction(void)
65 HttpSession* pSession = null;
66 HttpTransaction* pTransaction = null;
67 String* pProxyAddr = null;
68 String hostAddr(L"http://www.tizen.org");
70 pSession = new HttpSession();
71 r = pSession->Construct(NET_HTTP_SESSION_MODE_NORMAL, pProxyAddr ,hostAddr, null);
73 // Open a new HttpTransaction.
74 pTransaction = pSession->OpenTransactionN();
76 r = pTransaction->AddHttpTransactionListener(*this);
78 HttpRequest* pRequest = pTransaction->GetRequest();
79 r = pRequest->SetUri(L"http://www.tizen.org");
80 r = pRequest->SetMethod(NET_HTTP_METHOD_GET);
82 // Submit the HttpTransaction.
83 r = pTransaction->Submit();
89 class _OSP_EXPORT_ HttpTransaction
90 : public Tizen::Base::Object
95 * This destructor overrides Tizen::Base::Object::~Object().
99 virtual ~HttpTransaction(void);
103 * Submits the HTTP request.
107 * @privilege %http://tizen.org/privilege/http
109 * @return An error code
110 * @exception E_SUCCESS The method is successful.
111 * @exception E_OUT_OF_MEMORY The memory is insufficient.
112 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
113 * At least one of Uri, Method, Header, and Body is invalid.
114 * @exception E_INVALID_HEADER The header is @c null.
115 * @exception E_INVALID_STATE The method invoked is invalid.
116 * @exception E_OUT_OF_RANGE The submitted data is out of range.
117 * @exception E_MAX_EXCEEDED The number of active transactions has exceeded the maximum limit.
118 * @exception E_INVALID_PROXY The proxy server address is invalid.
119 * @exception E_DNS The DNS query has failed.
120 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
121 * @exception E_EMPTY_BODY The body is empty in a POST method case.
122 * @exception E_INVALID_SESSION The session is invalid.
123 * @exception E_AUTHENTICATION The authentication has failed.
124 * @exception E_UNKNOWN An unknown error has occurred.
125 * @exception E_SYSTEM A system error has occurred.
126 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
127 * @remarks The appropriate request header and body must be set using HttpRequest before using this method.
128 * If the session is in a non-pipeline mode, be sure not to submit a transaction before the previous transaction is completed.
134 * Gets the authentication information.
138 * @privilege %http://tizen.org/privilege/http
140 * @return A pointer to HttpAuthentication
141 * @exception E_SUCCESS The method is successful.
142 * @exception E_OUT_OF_MEMORY The memory is insufficient.
143 * @exception E_INVALID_STATE The method invoked is invalid.
144 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
145 * @exception E_SYSTEM A system error has occurred.
146 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
147 * @remarks The specific error code can be accessed using the GetLastResult() method.
149 HttpAuthentication* OpenAuthenticationInfoN(void);
152 * Gets a pointer to the HttpRequest related to the transaction. @n
153 * Setting a request header, method, URI, and body can be done by using the @c pHttpRequest pointer.
157 * @return The HttpRequest object pointer, @n
158 * else @c null in case of an invalid condition
159 * @exception E_SUCCESS The method is successful.
160 * @exception E_INVALID_STATE The method invoked is invalid.
161 * @exception E_INVALID_DATA The request is not valid.
162 * @remarks The specific error code can be accessed using the GetLastResult() method.
163 * @see Tizen::Net::Http::HttpRequest
165 HttpRequest* GetRequest(void) const;
168 * Gets a pointer to the HttpResponse related to the transaction. @n
169 * Getting a response header and body can be done by using the @c pHttpResponse pointer.
173 * @return The HttpResponse object pointer, @n
174 * else @c null if the response is not received
175 * @exception E_SUCCESS The method is successful.
176 * @exception E_INVALID_STATE The method invoked is invalid.
177 * @exception E_INVALID_DATA The response is not received.
178 * @remarks The specific error code can be accessed using the GetLastResult() method.
181 HttpResponse* GetResponse(void) const;
184 * Adds the IHttpTransactionEventListener instance. @n
185 * The added listener can listen to events as they are fired.
189 * @return An error code
190 * @param[in] listener The IHttpTransactionEventListener instance
191 * @exception E_SUCCESS The method is successful.
192 * @exception E_INVALID_STATE The method invoked is invalid.
193 * @exception E_OUT_OF_MEMORY The memory is insufficient.
194 * @exception E_OBJ_ALREADY_EXIST The listener is already added.
195 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, @n
196 * because the caller thread is a worker thread.
198 result AddHttpTransactionListener(IHttpTransactionEventListener& listener);
201 * Removes the IHttpTransactionEventListener instance.
205 * @return An error code
206 * @param[in] listener The IHttpTransactionEventListener instance
207 * @exception E_SUCCESS The method is successful.
208 * @exception E_INVALID_STATE The method invoked is invalid.
209 * @exception E_OBJ_NOT_FOUND The specified instance is not found within the indicated range, or
210 * the listener is already removed.
212 result RemoveHttpTransactionListener(IHttpTransactionEventListener& listener);
215 * Sets the IHttpProgressEventListener instance.
219 * @return An error code
220 * @param[in] listener The IHttpProgressEventListener instance
221 * @exception E_SUCCESS The method is successful.
222 * @exception E_INVALID_STATE The method invoked is invalid.
224 result SetHttpProgressListener(IHttpProgressEventListener& listener);
227 * Sets a user object to the instance of %HttpTransaction.
231 * @return An error code
232 * @param[in] pUserData The user data to set
233 * @exception E_SUCCESS The method is successful.
234 * @exception E_INVALID_STATE The method invoked is invalid.
236 result SetUserObject(const Tizen::Base::Object* pUserData);
239 * Gets a user object that is set to the instance of %HttpTransaction.
243 * @return An error code
245 Tizen::Base::Object* GetUserObject(void) const;
248 * Enables OnTransactionReadyToWrite.
252 * @return @c true if the OnTransactionReadyToWrite listener is active, @n
255 bool EnableTransactionReadyToWrite(void);
258 * Resumes the transaction after the IHttpTransactionEventListener::OnTransactionCertVerificationRequiredN() event is invoked. @n
259 * As described in the IHttpTransactionEventListener section, the above event occurs in case of the uncertified server certificate.
263 * @return An error code
264 * @exception E_SUCCESS The method is successful.
265 * @exception E_INVALID_STATE The current state of the instance prohibits the execution of the specified operation.
270 * Pauses the transaction after the IHttpTransactionEventListener::OnTransactionCertVerificationRequiredN() event is invoked. @n
271 * As described in the IHttpTransactionEventListener section, the above event occurs in case of the uncertified server certificate.
275 * @return An error code
276 * @exception E_SUCCESS The method is successful.
277 * @exception E_INVALID_STATE The current state of the instance prohibits the execution of the specified operation.
282 * Sets a client certificate to connect the server.
286 * @return An error code
287 * @param[in] certificateId The selected client certificate to set
288 * @exception E_SUCCESS The method is successful.
289 * @exception E_INVALID_ARG The specified input parameter is invalid.
290 * @exception E_INVALID_STATE This instance is in an invalid state.
291 * @remarks Start the AppControl(L"tizen.certificatemanager") for getting the selected client certificate. @n
292 * For more information, see <a href="../org.tizen.native.appprogramming/html/guide/app/appcontrol_certmgr.htm">here</a>.
294 result SetClientCertificate(int certificateId);
297 * Sets the timeout in seconds that is the timeout for waiting the transaction. @n
298 * A timeout value of zero means an infinite timeout.
302 * @return An error code
303 * @param[in] timeout A timeout for transaction
304 * @exception E_SUCCESS The method is successful.
305 * @exception E_INVALID_ARG The specified input parameter is invalid.
306 * @exception E_INVALID_STATE The transaction is already submitted, or
307 * the transaction is already closed.
309 result SetTimeout(int timeout);
312 * Sets the flag to verify server certificate. (By default, the flag is @c HTTP_CV_FLAG_AUTOMATIC.)
316 * @return An error code
317 * @param[in] flag Set the flag for certificate verification
318 * @exception E_SUCCESS The method is successful.
319 * @exception E_INVALID_STATE The method invoked is invalid.
320 * @exception E_SYSTEM A system error has occurred.
322 result SetServerCertificateVerification(NetHttpCertificateVerificationFlag flag = HTTP_CV_FLAG_AUTOMATIC);
326 * This default constructor is intentionally declared as private so that only the platform can create an instance.
328 HttpTransaction(void);
331 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
333 * @param[in] rhs An instance of %HttpTransaction
335 HttpTransaction(const HttpTransaction& rhs);
338 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
340 * @param[in] rhs An instance of %HttpTransaction
342 HttpTransaction& operator =(const HttpTransaction& rhs);
345 friend class _HttpTransactionImpl;
346 _HttpTransactionImpl* __pHttpTransactionImpl;
348 }; // HttpTransaction
350 } } } // Tizen::Net::Http
351 #endif // _FNET_HTTP_HTTP_TRANSACTION_H_