1 thttpevent.h

     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 

    17 

    18 /**

    19  @file THTTPEvent.h

    20  @warning : This file contains Rose Model ID comments - please do not delete

    21 */

    22 

    23 #ifndef	__THTTPEVENT_H__

    24 #define	__THTTPEVENT_H__

    25 

    26 // System includes

    27 #include <e32std.h>

    28 

    29 /**

    30 The HTTP UID. This UID is used for all events defined here.

    31 @publishedAll

    32 @released

    33 */

    34 const TUint KHTTPUid				= 0x1000A441;

    35 

    36 /**

    37 Wildcard Matching UID. When specified as part of an event then the UID event

    38 part of the match will be ignored.

    39 @publishedAll

    40 @released

    41 */

    42 const TUint KHTTPMatchAnyEventUid	=  0x1000A44C;

    43 

    44 /**

    45 The base status code for transaction events. Any number above this but below

    46 KSessionEventBaseStatus is a transaction event.

    47 @publishedAll

    48 @released

    49 */

    50 const TInt KTransactionEventBaseStatus		= 0;

    51 

    52 /**

    53 The base status code for transaction warning events.

    54 @publishedAll

    55 @released

    56 */

    57 const TInt KTransactionWarningBaseStatus	= 10000;

    58 

    59 /**

    60 The base status code for session events. Any number above this is a session 

    61 event.

    62 @publishedAll

    63 @released

    64 */

    65 const TInt KSessionEventBaseStatus			= 100000;

    66 

    67 /**

    68 The base status code for session warning events.

    69 @publishedAll

    70 @released

    71 */

    72 const TInt KSessionWarningBaseStatus		= 110000;

    73 

    74 

    75 //##ModelId=3C4C18740294

    76 class THTTPEvent

    77 /**

    78 A HTTP status message. Status messages consist of a UID and a

    79 status code within that UID. Extension dlls that needs to create

    80 new status messages should use their own UID and create status codes

    81 within that UID.

    82 @publishedAll

    83 @released

    84 */

    85 	{

    86 public:	

    87 

    88 	/** The TStandardEvent type is used to specify a family of event types. Any

    89 		negative event number is used to convey error codes. All events are 

    90 		incoming (originate with the origin server) unless otherwise indicated. 

    91 		Outgoing messages will not be seen by the MHTTPTransactionCallback's 

    92 		MHFRunL.

    93 	 */

    94 	enum TStandardEvent

    95 		{

    96 		/** Used when registering filter to indicate the filter is instrested 

    97 			in ALL events, both transaction and session events.

    98 		 */

    99 		EAll					= KRequestPending + 1,

   100 		/** Used when registering filters to indicate the filter is interested

   101 			in any transaction event, from any direction.

   102 		 */

   103 		EAnyTransactionEvent	= KRequestPending,

   104 		/** Used when registering filters to indicate the filter is interested 

   105 			in any session event.

   106 		 */

   107 		EAnySessionEvent		= KSessionEventBaseStatus

   108 		};

   109 

   110 	/** The TTransactionEvents type defines the events that correspond to 

   111 		transactions. Outgoing events originate from the client or from filters.

   112 		The clients do not send these explicitly since the API methods of 

   113 		RHTTPTransaction do it on their behalf. Incoming events originate from 

   114 		the protocol handler or from filters, and clients should handle these.

   115 		The ESucceeded and EFailed events are mutually exclusive, but one will

   116 		always be sent to the client as the final event for a transaction.

   117 	 */

   118 	enum TTransactionEvent

   119 		{

   120 		/** The transaction is being submitted. An outgoing event.

   121 		*/

   122 		ESubmit						= KTransactionEventBaseStatus,

   123 		/** The transaction is being cancelled. An outgoing event. 

   124 		*/

   125 		ECancel						= KTransactionEventBaseStatus + 1,

   126 		/** A new part of request body data is available for transmission. An

   127 			outgoing event

   128 		*/

   129 		ENotifyNewRequestBodyPart	= KTransactionEventBaseStatus + 2,

   130 		/** The transaction is being closed. An outgoing event. 

   131 		*/

   132 		EClosed						= KTransactionEventBaseStatus + 3,

   133 		/** All the response headers have been received. An incoming event. 

   134 		*/

   135 		EGotResponseHeaders			= KTransactionEventBaseStatus + 4, 

   136 		/** Some (more) body data has been received (in the HTTP response). An 

   137 			incoming event.

   138 		*/

   139 		EGotResponseBodyData		= KTransactionEventBaseStatus + 5,

   140 		/** The transaction's response is complete. An incoming event. 

   141 		*/

   142 		EResponseComplete			= KTransactionEventBaseStatus + 6,

   143 		/** Some trailer headers have been received. An incoming event.

   144 		*/

   145 		EGotResponseTrailerHeaders	= KTransactionEventBaseStatus + 7,

   146 		/** The transaction has succeeded. An incoming event.

   147 		*/

   148 		ESucceeded					= KTransactionEventBaseStatus + 8,

   149 		/** The transaction has failed. This is a 'catch-all' for communicating

   150 			failures, and more details of the failure should have been notified

   151 			in previous messages or status codes. If the client could process 

   152 			these then it is possible that it should not consider the transaction

   153 			a failure. For instance a browser that displays the body of 404 

   154 			responses to the user would not consider a 404 response to be a 

   155 			failure, as it would display it just like a 200 response even though

   156 			a 404 will be flagged as a 'failure'. An incoming event.

   157 		*/

   158 		EFailed						= KTransactionEventBaseStatus + 9, 

   159 		/** Generated from RHTTPTransaction::Fail(). A filter has failed in a 

   160 			way that prevents it from using the normal event mechanism to inform

   161 			the client of the error. This probably means it's run out of memory.

   162 			An incoming event.

   163 		*/

   164 		EUnrecoverableError			= KTransactionEventBaseStatus + 10,

   165 		/** An event that indicates that there is too much request data to be 

   166 			sent. The transaction will subsequently be cancelled. An incoming 

   167 			event.

   168 		*/

   169 		ETooMuchRequestData			= KTransactionEventBaseStatus + 11,

   170 

   171 		

   172 		/** If the returned status code for a transaciton is either 301, 302 or 307

   173             and the requested method is NOT a GET or HEAD, then the filter sends the 

   174             client an event ERedirectRequiresConfirmation as stated in RFC2616.

   175 

   176             On receiving this event, the transaction is already setup with the redirected URI

   177             and the client is required to make the decision to whether to submit the 

   178             transaction or close the transaction.

   179 

   180             If the requested method is GET or HEAD the transaction is automatically 

   181             redirected and this event is not used.

   182         */

   183 		ERedirectRequiresConfirmation = KTransactionEventBaseStatus + 12,

   184 

   185 		/** A transaction has been specified to use a proxy and the request

   186 			requires a tunnel to be establised to the origin server.

   187 		*/

   188 		ENeedTunnel					= KTransactionEventBaseStatus + 13,

   189 		

   190 		/** The client wishes to view the current cipher suite.

   191 		*/

   192 		EGetCipherSuite				= KTransactionEventBaseStatus + 14,

   193 		

   194 		/** The transaction's request is complete. An incoming event. 

   195 		*/

   196 		ERequestComplete			= KTransactionEventBaseStatus + 15,

   197 		

   198 		/**An event to signal that 100 Continue response has been received.

   199 		*/

   200 		EReceived100Continue		= KTransactionEventBaseStatus + 16,

   201 		

   202 		/**An event to cancel the wait for a 100-Continue event.

   203 		*/

   204 		ECancelWaitFor100Continue	= KTransactionEventBaseStatus + 17,

   205 

   206 		/**An event of Send Timeout for a Request.

   207 		*/

   208 		ESendTimeOut	= KTransactionEventBaseStatus + 18,

   209 

   210 		/**An event of Receive Timeout for a Response.

   211 		*/

   212 		EReceiveTimeOut	= KTransactionEventBaseStatus + 19

   213 

   214 		};

   215 

   216 	/** The TDirection type defines the direction of an event. An outgoing event

   217 		originates from the client or from filters. The clients do not send these

   218 		explicitly since the API methods of RHTTPTransaction or RHTTPSession do 

   219 		it on their behalf. Incoming events originate from the protocol handler 

   220 		or from filters, and clients should handle these.

   221 	*/

   222 	enum TDirection

   223 		{

   224 		/** An event originating with the client (e.g. start transaction).

   225 		*/

   226 		EOutgoing,

   227 		/** An event originating with the server (e.g. something received). 

   228 		*/

   229 		EIncoming

   230 		};

   231 

   232 	/** The TTransactionWarning type indicates that something in a transaction 

   233 		may be incorrect but the transaction may continue. It may also indicate 

   234 		that something (e.g. a filter) may have performed an action that has 

   235 		changed the transaction and that the client should be informed of this.

   236 	*/

   237 	enum TTransactionWarning

   238 		{

   239 		/** An event indicating that the transaction has been redirected and the

   240 			original origin server indicated that it was a permanent redirection.

   241 			The URI for the transaction is now the redirected location. A 

   242 			permanent redirection may require further client behavior if the 

   243 			request came from a stored URI. This is to avoid further redirections 

   244 			on subsequent requests for this resource.

   245 		*/

   246 		ERedirectedPermanently			= KTransactionWarningBaseStatus,

   247 		/** An event indicating that the transaction has been redirected and the

   248 			original server indicated that it was a temporary redirection. 

   249 		*/

   250 		ERedirectedTemporarily			= KTransactionWarningBaseStatus + 1,

   251 		/** An event generated by the Protocol Handler when it receives a Content-

   252 			Length value that does not match the actual length of the body data.

   253 		*/

   254 		EMoreDataReceivedThanExpected	= KTransactionWarningBaseStatus + 2

   255 		};

   256 

   257 public:	// Methods

   258 

   259 	/** Constructor

   260 		@param aStatus	The status value.

   261 		@param aUID		The UID.

   262 	*/

   263 	//##ModelId=3C4C187402FB

   264 	inline THTTPEvent(TInt aStatus, TUint aUID = KHTTPUid);

   265 

   266 	/** Constructor (using a standard event and the HTTP UID)

   267 		@param aStatus	The standard event to use.

   268 	*/

   269 	//##ModelId=3C4C18740304

   270 	inline THTTPEvent(TStandardEvent aStatus = EAnyTransactionEvent);

   271 

   272 	/** Constructor (using a transaction event and the HTTP UID)

   273 		@param aStatus	The transaction event to use.

   274 	*/

   275 	//##ModelId=3C4C1874030C

   276 	inline THTTPEvent(TTransactionEvent aStatus);

   277 

   278 	/** Assigns a standard event code to an event object

   279 		@param aStatus	The standard event.

   280 		@return The HTTP event object.

   281 	*/

   282 	//##ModelId=3C4C187402EF

   283 	inline THTTPEvent& operator=(TStandardEvent aStatus);

   284 

   285 	/** Assigns a transaction event code to an event object

   286 		@param aStatus	The transaction event.

   287 		@return The HTTP event object.

   288 	*/

   289 	//##ModelId=3C4C187402F1

   290 	inline THTTPEvent& operator=(TTransactionEvent aStatus);

   291 

   292 	/** Equality operator

   293 		@param The HTTP event object to compare.

   294 		@return ETrue if the HTTP event objects are equal. 

   295 	*/

   296 	//##ModelId=3C4C187402DA

   297 	inline TBool operator==(THTTPEvent aThat) const;

   298 

   299 	/** Inequality operator

   300 		@param The HTTP event object to compare.

   301 		@return ETrue if the HTTP event objects are not equal. 

   302 	*/

   303 	//##ModelId=3C4C187402BD

   304 	inline TBool operator!=(THTTPEvent aThat) const;

   305 

   306 	/** Equality operator (compares with a standard event)

   307 		@param The standard event object to compare.

   308 		@return ETrue if the standard event objects are equal.

   309 	*/

   310 	//##ModelId=3C4C187402DC

   311 	inline TBool operator==(TStandardEvent aStatus) const;

   312 

   313 	/** Inequality operator (compares with a standard event)

   314 		@param The standard event object to compare.

   315 		@return ETrue if the standard event objects are not equal. 

   316 	*/

   317 	//##ModelId=3C4C187402C7

   318 	inline TBool operator!=(TStandardEvent aStatus) const;

   319 

   320 	/** Equality operator (compares with a transaction event)

   321 		@param The transaction event object to compare.

   322 		@return ETrue if the transaction event objects are equal. 

   323 	*/

   324 	//##ModelId=3C4C187402E4

   325 	inline TBool operator==(TTransactionEvent aStatus) const;

   326 

   327 	/** Inequality operator (compares with a transaction event)

   328 		@param The transaction event object to compare.

   329 		@return ETrue if the transaction event objects are not equal. 

   330 	*/

   331 	//##ModelId=3C4C187402D0

   332 	inline TBool operator!=(TTransactionEvent aStatus) const;

   333 	

   334 	/** @return ETrue if the event is a session event

   335 	*/

   336 	//##ModelId=3C4C187402BC

   337 	inline TBool IsSessionEvent() const;

   338 

   339 public:	// Attributes

   340 

   341 	/** The status value.

   342 	 */

   343 	//##ModelId=3C4C187402B4

   344 	TInt iStatus;

   345 

   346 	/** The UID.

   347 	 */

   348 	//##ModelId=3C4C187402AA

   349 	TUint iUID;

   350 

   351 protected: // Attributes

   352 	/** Flag to indicate whether the event is a session event

   353 	*/

   354 	TBool iIsSessionEventFlag;

   355 

   356 	};

   357 

   358 

   359 class THTTPSessionEvent : public THTTPEvent

   360 /**

   361 A HTTP session status message. Status messages consist of a UID and a

   362 status code within that UID. Extension dlls that needs to create

   363 new status messages should use their own UID and create status codes

   364 within that UID.

   365 @publishedAll

   366 @released

   367 */

   368 	{

   369 public: // Enumerations

   370 	/** The TSessionEvents type defines the evenst that correspond to the 

   371 		of a session entity. Outgoing events originate from the client or from

   372 		filters. Incoming events originate from the protocol handler or from 

   373 		filters, and clients should handle these. 

   374 	*/

   375 	enum TSessionEvent

   376 		{

   377 		/** A session connection should be initiated. An outgoing event.

   378 		*/

   379 		EConnect							= KSessionEventBaseStatus,

   380 		/** The session should be disconnected. An outgoing event.

   381 		 */

   382 		EDisconnect							= KSessionEventBaseStatus + 1,

   383 		/** The session has been successfully connected. None of the client 

   384 			requested capabilities were denied or reduced by the proxy. An 

   385 			incoming event.

   386 		*/

   387 		EConnectedOK						= KSessionEventBaseStatus + 2,

   388 		/** The session has been connected, but with one or more of the client 

   389 			requested capabilities denied or reduced by the proxy. An incoming 

   390 			event.

   391 		*/

   392 		EConnectedWithReducedCapabilities	= KSessionEventBaseStatus + 3,

   393 		/** The session has been disconnected. This either confirms an earlier 

   394 			EDisconnect event or indicates a forced disconnection by the proxy. 

   395 			An incoming event.

   396 		*/

   397 		EDisconnected						= KSessionEventBaseStatus + 4,

   398 		/** The authentication handshake succeeded with the automatic validation

   399 			of the (proxy) server certificate.

   400 		 */

   401 		EAuthenticatedOK					= KSessionEventBaseStatus + 5,

   402 		/** The authentication handshake failed.

   403 		*/

   404 		EAuthenticationFailure				= KSessionEventBaseStatus + 6,

   405 		/** The connection attempt to the proxy timed out.

   406 		*/

   407 		EConnectionTimedOut					= KSessionEventBaseStatus + 7

   408 		};

   409 	

   410 	/**

   411 		HTTP session warning events.

   412 	 */

   413 	enum TSessionWarning

   414 		{

   415 		/** The client has requested a transaction event that requires a session

   416 			to be connected or the connection to be initiated, but neither is

   417 			currently true. The transaction event will be left pending until the

   418 			session is connected. An incoming event.

   419 		*/

   420 		ENotConnected						= KSessionWarningBaseStatus,

   421 		/** The proxy has sent some information that is not related to a 

   422 			transaction and has no effect on the state of the session. The 

   423 			information from the proxy is in the EProxyExceptionInfo property.

   424 		*/

   425 		EExceptionInfo						= KSessionWarningBaseStatus + 1,

   426 		/** The client connection request was (permanently) redirected to a new

   427 			WAP proxy address. The client should check the EWspProxyAddress 

   428 			property for the new address. The client's access-point database can

   429 			then be updated with this address. No notification is given of a 

   430 			temporary redirection.

   431 		*/

   432 		ERedirected							= KSessionWarningBaseStatus + 2,

   433 		/** The client has requested a session event that is not valid whilst

   434 			the WSP session is trying to establish a connection.

   435 		*/

   436 		EAlreadyConnecting					= KSessionWarningBaseStatus + 3,

   437 		/** The client has requested a session event that is not valid whilst

   438 			the WSP session is in the Connected state.

   439 		*/

   440 		EAlreadyConnected					= KSessionWarningBaseStatus + 4,

   441 		/** The client has requested a session event that is not valid whilst

   442 			the WSP session is trying to close the connection.

   443 		*/

   444 		EAlreadyDisconnecting				= KSessionWarningBaseStatus + 5,

   445 		/** The client has requested a session event that is not valid whilst

   446 			the WSP session is in the Null (or disconnected) state.

   447 		*/

   448 		EAlreadyDisconnected				= KSessionWarningBaseStatus + 6

   449 		};

   450 

   451 public:

   452 	/** Constructor

   453 		@param aStatus	The status value.

   454 		@param aUID		The UID.

   455 	*/

   456 	inline THTTPSessionEvent(TInt aStatus, TUint aUID = KHTTPUid);

   457 

   458 	/** Constructor (using a standard event and the HTTP UID)

   459 		@param aStatus	The standard event to use.

   460 	*/

   461 	inline THTTPSessionEvent(TStandardEvent aStatus = EAnySessionEvent);

   462 

   463 	/** Constructor (using a session event and the HTTP UID)

   464 		@param aStatus	The session event to use.

   465 	*/

   466 	inline THTTPSessionEvent(TSessionEvent aStatus);

   467 

   468 	/** Assigns a session event code to an event object

   469 		@param aStatus	The session event.

   470 	*/

   471 	//##ModelId=3C4C187402F9

   472 	inline THTTPSessionEvent& operator=(TSessionEvent aStatus);

   473 

   474 	/// Equality operator (compares with a session event)

   475 	//##ModelId=3C4C187402E6

   476 	inline TBool operator==(TSessionEvent aStatus) const;

   477 

   478 	/// Inequality operator (compares with a session event)

   479 	//##ModelId=3C4C187402D2

   480 	inline TBool operator!=(TSessionEvent aStatus) const;

   481 	};

   482 

   483 #include <http/thttpevent.inl>

   484 

   485 #endif // __THTTPEVENT_H__