1 wapmessage.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 #ifndef __WAPMESSAGE_H__

    17 #define __WAPMESSAGE_H__

    18 

    19 

    20 #include <e32base.h>

    21 #include <e32std.h>

    22 #include <in_sock.h>

    23 #include <nifman.h>

    24 #include <in_iface.h>

    25 

    26 /** 

    27 * @file

    28 *

    29 * The WAP Messaging API.  

    30 *

    31 * Four interfaces are defined that provide bound and fully-specified versions of WDP and Connectionless Push.

    32 * An instantiation of each may be obtained using the CreateImplementationL() function, and must be released 

    33 * using Release() when no longer required.  Release() causes the instantiation to be deleted.

    34 *

    35 * For error codes returned by methods in this API, see <wapmsgerr.h>.  Most methods can return a set of general 

    36 * errors, with some returning additional specific errors.

    37 *

    38 * @publishedAll

    39 * @released since v7.0

    40 */

    41 

    42 /** 

    43 * Defines WAP-related types and error codes. 

    44 */

    45 namespace Wap

    46 	{

    47 	// Bearer type definition

    48 	typedef enum

    49 	/** Type definition for an enum defining WAP bearer types. */

    50 		{

    51 		/** All bearers. */

    52 		EAll,

    53 		/** Internet Protocol. */

    54 		EIP,

    55 		/** 7-bit SMS. */

    56 		ESMS7,

    57 		/** 8-bit SMS. */

    58 		ESMS,

    59 		/** 7-bit SMS. The bearers WAPSMS and WAPSMS7 are intended for WAP browsing where 

    60 		delivery reports are not required and the validity period is much shorter (5 minutes). */

    61 		EWAPSMS7,

    62 		/** 8-bit SMS. */

    63 		EWAPSMS

    64 		} TBearer;

    65 

    66 	// Port number definition

    67 	/** A port number. */

    68 	typedef TUint16 TPort;

    69  

    70 	class TAddressInfo

    71 	/** Encapsulates an interface name and address. */

    72 		{

    73 	public:

    74 		/** Interface name. */

    75 		TName iName;

    76 		/** Interface IP address. */

    77 		TInetAddr iAddress;

    78 		};

    79 	}

    80 

    81 

    82 /**

    83 * The WSP status type definition.

    84 * @internalComponent

    85 */

    86 typedef TUint8 TWSPStatus;

    87 	

    88 /** Bound WDP */

    89 class CWapBoundDatagramService : public CBase

    90 /** 

    91 * Sends and receives datagrams over WDP using a specified local port.

    92 *

    93 * The class is an ECom plug-in interface. Clients use NewL() to request an implementation 

    94 * of the interface, and then call the interface's virtual functions to access 

    95 * the implementation's services. 

    96 *

    97 * The use of the plug-in architecture allows different implementations to use 

    98 * different underlying WAP stacks.

    99 *

   100 * Functions can return system wide error codes, and also API-specific errors 

   101 * as defined in wapmsgerr.h. 

   102 * 

   103 */

   104 	{

   105 public: // creation/deletion

   106 	IMPORT_C static CWapBoundDatagramService* NewL();

   107 	IMPORT_C static CWapBoundDatagramService* NewL(const TUid& aImplementation);

   108 	IMPORT_C virtual ~CWapBoundDatagramService();

   109 

   110 public: // API methods

   111 

   112 	/** 

   113 	* Connects to the WAP stack, opening an endpoint that can be used to listen for 

   114 	* subsequent incoming datagrams.

   115 	*

   116 	* This overload of Connect() allows an IP address associated with a network 

   117 	* interface to be specified. In multihomed systems, this can be used to specify 

   118 	* the network interface to which the endpoint should be bound.

   119 	* 

   120 	* All CWapBoundDatagramService implementations must automatically close this 

   121 	* endpoint upon destruction.

   122 	* 

   123 	* @param aBearer	The bearer to listen on. Use EAll to specify all bearers.

   124 	* @param aPort		The port to listen on. If set to 0, a local port will be chosen 

   125 	* 					for the client's first SendTo()

   126 	* @param aInetAddr	The IP address of the network interface that should be used 

   127 	*					in a multihomed system.

   128 	* @return			KErrNone on successful completion, or one of the system error codes 

   129 	* 					on failure.

   130 	*/

   131 	virtual TInt Connect(Wap::TBearer aBearer, Wap::TPort aPort,TInetAddr aInetAddr)=0;

   132 

   133 	/** 

   134 	* Connects to the WAP stack, opening an endpoint that can be used to listen for 

   135 	* subsequent incoming datagrams.

   136 	* 

   137 	* All CWapBoundDatagramService implementations must automatically close this 

   138 	* endpoint upon destruction. 

   139 	* 

   140 	* @param aBearer	The bearer to listen on. Use EAll to specify all bearers.

   141 	* @param aPort		The port to listen on. If set to 0, a local port will be chosen 

   142 	* 					for the client's first SendTo()

   143 	* @return			KErrNone on successful completion, or one of the system error codes 

   144 	* 					on failure.

   145 	*/

   146 	virtual TInt Connect(Wap::TBearer aBearer,Wap::TPort aPort)=0;

   147 

   148 	/** Sends data to a remote endpoint. 

   149 	* 

   150 	* @param aRemoteHost	The address of the remote host to which to send the data. 

   151 	* 						The format of the address is bearer-specific.

   152 	* @param aRemotePort	The port on the remote host to which the data will be sent

   153 	* @param aBuffer		The data buffer to be sent

   154 	* @param aBearer		The bearer to be used, if the bound connection was opened with EAll

   155 	* @return				KErrNone on successful completion, or one of the system error codes 

   156 	* 						on failure.

   157 	*/

   158 virtual TInt SendTo(const TDesC8& aRemoteHost, Wap::TPort aRemotePort, const TDesC8& aBuffer, Wap::TBearer aBearer)=0;

   159 

   160 	/** 

   161 	* Waits for a datagram to be received, and discovers the size of buffer required 

   162 	* to retrieve it.

   163 	* 

   164 	* This asynchronous method waits for a datagram to be received and will then 

   165 	* complete allowing the client to discover how large a buffer is needed to retrieve 

   166 	* the entire datagram that has been received. A later call to RecvFrom() with 

   167 	* a buffer of sufficient size will then allow the client to retrieve the datagram 

   168 	* fully. 

   169 	* 

   170 	* @param aDataSizePckg	On completion, the size of data received, in bytes

   171 	* @param aReqStatus		Asynchonrous status word, used to signal when a data size is known

   172 	* @return				KErrNone on successful completion, or one of the system error codes 

   173 	* 						on failure.

   174 	*/

   175 	virtual TInt AwaitRecvDataSize(TPckg<TUint16>& aDataSizePckg, TRequestStatus& aReqStatus)=0;

   176 

   177 	/** 

   178 	* Receives data on a bound port. 

   179 	* 

   180 	* An asynchronous notification is sent to the client when data arrives. 

   181 	* 

   182 	* @param aRemoteHost	On completion, the bearer-dependent address of the remote 

   183 	* 						host from which the data was received

   184 	* @param aRemotePort	On completion, the port on the remote host from which the 

   185 	* 						data was received

   186 	* @param aBuffer		A client-allocated data buffer that on completion is filled 

   187 	* 						with data received. Data that overflows the buffer is discarded.

   188 	* @param aTruncated		On completion, indicates whether the received datagram was 

   189 	* 						truncated to fit in the client's supplied buffer

   190 	* @param aReqStatus		Asynchronous status word, used to notify the client that 

   191 	* 						a datagram was received

   192 	* @param aTimeout		An optional millisecond time-out which allows a timed read 

   193 	* 						to be made. If no data is received within the timeout period, the request 

   194 	* 						completes with KErrTimedOut. If a value of 0 is supplied, the timeout is infinite.

   195 	* @return				KErrNone on successful completion, or one of the system error codes on failure. 

   196 	*/

   197 	virtual TInt RecvFrom(TDes8& aRemoteHost, Wap::TPort& aRemotePort, TDes8& aBuffer, TBool& aTruncated, 

   198 							TRequestStatus& aReqStatus, TUint32 aTimeout)=0;

   199  

   200 	/** 

   201 	* Cancels a previously asynchronous RecvFrom() or AwaitRecvDataSize() request. 

   202 	*

   203 	* If a datagram arrives at the local host, it will be discarded. 

   204 	* 

   205 	*/

   206 	virtual void CancelRecv()=0;

   207 

   208 	/** 

   209 	* Gets the local port of this endpoint.

   210 	* 

   211 	* This is useful if the port was chosen automatically.

   212 	* 

   213 	* @param aPort	On return, the port number

   214 	* @return		KErrNone on successful completion, or one of the system error codes on failure. 

   215 	*/

   216 	virtual TInt GetLocalPort(Wap::TPort& aPort)=0;

   217 

   218 	/** 

   219 	* Gets the local address of this endpoint. 

   220 	* 

   221 	* @param aLocalHost	On return, the address of the local host. Clients must pass 

   222 	* 					in a reference to a NULL HBufC8 pointer. The function allocates a new HBufC8 

   223 	* 					buffer to hold the address, and passes ownership of the buffer to the client.

   224 	* @return			KErrNone on successful completion, or one of the system error codes on failure.

   225 	*/

   226 	virtual TInt GetLocalAddress(HBufC8*& aLocalHost)=0;

   227 

   228 	/** 

   229 	* Gets the bearer on which a received datagram arrived. 

   230 	* 

   231 	* This is useful when EAll was specified as the bearer in Connect().

   232 	* 

   233 	* @param aBearer	On return, the bearer

   234 	* @return			KErrNone on successful completion, or one of the system error codes on failure.	

   235 	*/

   236 	virtual TInt GetBearer(Wap::TBearer& aBearer)=0;

   237 

   238 	/** 

   239 	* Queries the WDP bearer for its maximum datagram size and its nominal datagram size.

   240 	*

   241 	* The nominal size is the size within which a datagram won't have to be split 

   242 	* into smaller individual messages and then re-assembled at the other end. 

   243 	* 

   244 	* The function will fail for a stream connection.

   245 	*

   246 	* @param aMaxSize		On return, the maximum datagram size

   247 	* @param aNominalSize	On return, the nominal datagram size

   248 	* @return				KErrNone on successful completion, or one of the system error codes 

   249 	*						on failure.

   250 	*/	

   251 	virtual TInt GetDatagramSizes(TUint16& aMaxSize, TUint16& aNominalSize)=0;

   252 	

   253 protected: // methods

   254 	IMPORT_C CWapBoundDatagramService();

   255 	IMPORT_C void ConstructL();

   256 

   257 private: // attributes

   258 	/// D'tor Key identification required for ECOM

   259 	TUid iDtor_ID_Key;

   260 	};

   261 

   262 /** Fully-Specified WDP

   263 */

   264 class CWapFullySpecDatagramService : public CBase

   265 /** 

   266 * Sends and receives datagrams over WDP using a specified local port and a single, 

   267 * named remote host.

   268 * 

   269 * The class is an ECom plug-in interface. Clients use NewL() to request an implementation 

   270 * of the interface, and then call the interface's virtual functions to access 

   271 * the implementation's services. 

   272 * 

   273 * The use of the plug-in architecture allows different implementations to use 

   274 * different underlying WAP stacks.

   275 * 

   276 * Functions can return system wide error codes, and also API-specific errors 

   277 * as defined in wapmsgerr.h. 

   278 */

   279 	{

   280 public: // creation/deletion

   281 	IMPORT_C static CWapFullySpecDatagramService* NewL();

   282 	IMPORT_C static CWapFullySpecDatagramService* NewL(const TUid& aImplementation);

   283 	IMPORT_C virtual ~CWapFullySpecDatagramService();

   284 

   285 public: // API methods

   286 

   287 	// Connect to the wapstack, opening an endpoint which is to be used only with a single, named remote host.

   288 	/** 

   289 	* Connects to the WAP stack, opening an endpoint that can be used to listen for 

   290 	* subsequent incoming datagrams.

   291 	*	

   292 	* This overload of Connect() allows an IP address associated with a network 

   293 	* interface to be specified. In multihomed systems, this can be used to specify 

   294 	* the network interface to which the endpoint should be bound.

   295 	* 

   296 	* All CWapFullySpecDatagramService implementations must automatically close 

   297 	* this endpoint upon destruction.

   298 	* 

   299 	* @param aRemoteHost	The bearer-dependent address of the remote host with which 

   300 	* 						the data will be exchanged

   301 	* @param aRemotePort	The port on the remote host to which data will be sent

   302 	* @param aBearer		The bearer to use. EAll cannot be used.

   303 	* @param aInetAddr		The IP address of the network interface that should be used 

   304 	* 						in a multihomed system.

   305 	* @return				KErrNone on successful completion, or one of the system error codes on failure. 

   306 	*/

   307 	virtual TInt Connect(const TDesC8& aRemoteHost, Wap::TPort aRemotePort, Wap::TBearer aBearer, TInetAddr aInetAddr)=0;

   308 

   309 	// Connect to the wapstack, opening an endpoint which is to be used only with a single, named remote host.

   310 	/** 

   311 	* Connects to the WAP stack, opening an endpoint that can be used to listen for 

   312 	* subsequent incoming datagrams.

   313 	* 

   314 	* All CWapFullySpecDatagramService implementations must automatically close 

   315 	* this endpoint upon destruction.

   316 	* 

   317 	* @param aRemoteHost	The bearer-dependent address of the remote host with which 

   318 	* 						the data will be exchanged

   319 	* @param aRemotePort	The port on the remote host to which data will be sent

   320 	* @param aBearer		The bearer to use. EAll cannot be used.

   321 	* @return 				KErrNone on successful completion, or one of the system error codes on failure. 

   322 	*/

   323 	virtual TInt Connect(const TDesC8& aRemoteHost, Wap::TPort aRemotePort, Wap::TBearer aBearer)=0;

   324 

   325 	/** 

   326 	* Sends data on a fully-specified connection.

   327 	* 

   328 	* @param aBuffer	The data buffer to be written over the connection

   329 	* @return			KErrNone on successful completion, or one of the system error codes on failure. 

   330 	*/

   331 	virtual TInt Send(const TDesC8& aBuffer)=0;

   332 

   333 	/** 

   334 	* Waits for a datagram to be received, and discover how large a buffer is required 

   335 	* to retrieve it.

   336 	* 

   337 	* This asynchronous request waits for a datagram to be received and will then 

   338 	* complete allowing the client to discover how large a buffer is needed to retrieve 

   339 	* the entire datagram that has been received. A later call to Recv() with a 

   340 	* buffer of sufficent size will then allow the client to retrieve the datagram 

   341 	* fully. 

   342 	* 

   343 	* @param aDataSizePckg	On completion, the size of data received, in bytes

   344 	* @param aReqStatus		Asynchonrous status word, used to signal when a data size is known

   345 	* @return				KErrNone on successful completion, or one of the system error codes on failure. 

   346 	*/

   347 	virtual TInt AwaitRecvDataSize(TPckg<TUint16>& aDataSizePckg, TRequestStatus& aReqStatus)=0;

   348 

   349 	/** 

   350 	* Receives data on a bound port. 

   351 	* 

   352 	* An asynchronous notification is sent to the client when data arrives. 

   353 	* 

   354 	* @param aBuffer	A client-allocated data buffer that, on completion, is filled 

   355 	* 					with data received. Data that overflows the buffer is discarded.

   356 	* @param aTruncated	On completion, indicates whether the received datagram was 

   357 	* 					truncated to fit in the client's supplied buffer

   358 	* @param aReqStatus	Asynchronous status word, used to notify the client that 

   359 	* 					a datagram was received

   360 	* @param aTimeout	An optional millisecond time-out which allows a timed read 

   361 	* 					to be made. If no data is received within the timeout period, the request 

   362 	* 					completes with KErrTimedOut. If a value of 0 is supplied, the timeout is infinite.

   363 	* @return			KErrNone on successful completion, or one of the system error codes on failure. 

   364 	*/

   365 	virtual TInt Recv(TDes8& aBuffer, TBool& aTruncated, TRequestStatus& aReqStatus, TUint32 aTimeout)=0;

   366 

   367 	/** 

   368 	* Cancels a previously asynchronous Recv() or AwaitRecvDataSize() request. 

   369 	* 

   370 	* If a datagram arrives at the local host, it will be discarded. 

   371 	* 

   372 	*/

   373 	virtual void CancelRecv()=0;

   374 

   375 	/** 

   376 	* Gets the local port of this endpoint.

   377 	* 

   378 	* This is useful if the port was chosen automatically.

   379 	* 

   380 	* @param aPort	On return, the port number

   381 	* @return		KErrNone on successful completion, or one of the system error codes on failure. 

   382 	*/

   383 	virtual TInt GetLocalPort(Wap::TPort& aPort)=0;

   384 

   385 	/** 

   386 	* Gets the local address of this endpoint. 

   387 	* 

   388 	* @param aLocalHost	On return, the address of the local host. Clients must pass 

   389 	* 					in a reference to a NULL HBufC8 pointer. The function allocates a new HBufC8 

   390 	* 					buffer to hold the address, and passes ownership of the buffer to the client.

   391 	* @return			KErrNone on successful completion, or one of the system error codes on failure. 

   392 	*/

   393 	virtual TInt GetLocalAddress(HBufC8*& aLocalHost)=0;

   394 

   395 	/** 

   396 	* Queries the WDP bearer for its maximum datagram size and its nominal datagram size.

   397 	* 

   398 	* The nominal size is the size within which a datagram won't have to be split 

   399 	* into smaller individual messages and then re-assembled at the other end. 

   400 	* 

   401 	* @param aMaxSize		On return, the maximum datagram size

   402 	* @param aNominalSize	On return, the nominal datagram size

   403 	* @return				KErrNone on successful completion, or one of the system error codes on failure. 

   404 	*/

   405 	virtual TInt GetDatagramSizes(TUint16& aMaxSize, TUint16& aNominalSize)=0;

   406 	

   407 protected: // methods

   408 	IMPORT_C CWapFullySpecDatagramService();

   409 	IMPORT_C void ConstructL();

   410 

   411 private: // ECOM

   412 	// D'tor Key identification required for ECOM

   413 	TUid iDtor_ID_Key;

   414 	};

   415 

   416 /** Bound Connectionless Push

   417 */

   418 class CWapBoundCLPushService : public CBase

   419 /** 

   420 * Listens for WAP Push messages from any sender.

   421 * 

   422 * The class is an ECom plug-in interface. Clients use NewL() to request an implementation 

   423 * of the interface, and then call the interface's virtual functions to access 

   424 * the implementation's services. 

   425 * 

   426 * The use of the plug-in architecture allows different implementations to use 

   427 * different underlying WAP stacks.

   428 * 

   429 * Functions can return system wide error codes, and also API-specific errors 

   430 * as defined in wapmsgerr.h. 

   431 * 

   432 */

   433 {

   434 public: // creation/deletion

   435 	IMPORT_C static CWapBoundCLPushService* NewL();

   436 	IMPORT_C static CWapBoundCLPushService* NewL(const TUid& aImplementation);

   437 	IMPORT_C virtual ~CWapBoundCLPushService();

   438 

   439 public: // API methods

   440 

   441 	

   442 	// Opens a socket which is to be used to listen for subsequent incoming Push messages from any sender;

   443 	// i.e. it has only been 'bound' to the local address	 

   444 	/** 

   445 	* Connects to the WAP stack, opening an endpoint that can be used to listen for 

   446 	* Push messages from any sender.

   447 	* 

   448 	* This overload of Connect() allows an IP address associated with a network 

   449 	* interface to be specified. In multihomed systems, this can be used to specify 

   450 	* the network interface to which the endpoint should be bound.

   451 	* 

   452 	* All CWapBoundCLPushService implementations must automatically close this endpoint 

   453 	* upon destruction.

   454 	* 

   455 	* @param aBearer	The bearer to listen on. Use EAll to specify all bearers.

   456 	* @param aPort		The port to listen on. If set to 0, a local port will be chosen 

   457 	* 					for the client's first SendTo()

   458 	* @param aSecure	Security flag to indicate whether WTLS should be used or not

   459 	* @param aInetAddr	The address of the adapter to use

   460 	* @return			KErrNone on successful completion, or one of the system error codes on failure. 

   461 	*/

   462 	virtual TInt Connect(Wap::TBearer aBearer, Wap::TPort aPort, TBool aSecure, TInetAddr aInetAddr)=0;

   463 

   464 	

   465 	// Opens a socket which is to be used to listen for subsequent incoming Push messages from any sender;

   466 	// i.e. it has only been 'bound' to the local address

   467 	/** 

   468 	* Connects to the WAP stack, opening an endpoint that can be used to listen for 

   469 	* Push messages from any sender.

   470 	* 

   471 	* All CWapBoundCLPushService implementations must automatically close this endpoint 

   472 	* upon destruction.

   473 	* 

   474 	* @param aBearer	The bearer to listen on. Use EAll to specify all bearers.

   475 	* @param aPort		The port to listen on. If set to 0, a local port will be chosen 

   476 	* 					for the client's first SendTo()

   477 	* @param aSecure	Security flag to indicate whether WTLS should be used or not

   478 	* @return			KErrNone on successful completion, or one of the system error codes on failure. 

   479 	*/

   480 	virtual TInt Connect(Wap::TBearer aBearer, Wap::TPort aPort, TBool aSecure)=0;

   481 

   482 	/** 

   483 	* Requests an asynchronous notification upon arrival of the next push message 

   484 	* on the listening connection.

   485 	* 

   486 	* The request completes upon receipt of the message, filling the buffers with 

   487 	* as much received data as possible. A return code indicates whether further 

   488 	* data remains. The call must be re-issued for subsequent messages or to receive 

   489 	* remaining data from a previous push message.

   490 	* 

   491 	* @param aPushHeaders	A client-allocated buffer that, on completion, is filled 

   492 	* 						with the push message's header data

   493 	* @param aPushBody		A client-allocated buffer that, on completion, is filled with 

   494 	* 						the push message's body data

   495 	* @param aPushIdPckg	On completion, an integer ID that uniquely specifies the 

   496 	* 						push message

   497 	* @param aReqStatus		Asynchonrous status word, used by the service provider to 

   498 	* 						notify the client when a push message has arrived. 

   499 	*						EMoreData is returned if more pushed data is available.

   500 	* @return				KErrNone on successful completion, or one of the system error codes on failure. 

   501 	*/

   502 	virtual TInt AwaitPush(TDes8& aPushHeaders, TDes8& aPushBody, TPckgBuf<TUint8>& aPushIdPckg, TRequestStatus& aReqStatus)=0;

   503 

   504 	/** 

   505 	* Cancels a previous push message request.

   506 	* 

   507 	* If a push message arrives, the client will not be notified. 

   508 	*

   509 	*/

   510 	virtual void CancelAwaitPush()=0;

   511 

   512 	/** 

   513 	* Gets the local port of this endpoint.

   514 	* 

   515 	* This is useful if the port was chosen automatically. 

   516 	* 

   517 	* @param aPort	On return, the port number

   518 	* @return		KErrNone on successful completion, or one of the system error codes on failure. 

   519 	*/

   520 	virtual TInt GetLocalPort(Wap::TPort& aPort)=0;

   521 

   522 	/** 

   523 	* Gets the local address of this endpoint. 

   524 	* 

   525 	* @param aLocalHost	On return, the address of the local host. Clients must pass 

   526 	* 					in a reference to a NULL HBufC8 pointer. The function allocates a new HBufC8 

   527 	* 					buffer to hold the address, and passes ownership of the buffer to the client.

   528 	* @return			KErrNone on successful completion, or one of the system error codes on failure. 

   529 	*/

   530 	virtual TInt GetLocalAddress(HBufC8*& aLocalHost)=0;

   531 

   532 	/** 

   533 	* Gets the bearer on which a received datagram arrived. 

   534 	* 

   535 	* This is useful when EAll was specified as the bearer in Connect().

   536 	* 

   537 	* @param aBearer	On return, the bearer

   538 	* @return			KErrNone on successful completion, or one of the system error codes on failure. 

   539 	*/

   540 	virtual TInt GetBearer(Wap::TBearer& aBearer)=0;

   541 

   542 	/**

   543 	 * Gets the address of the remote server.

   544 	 *

   545 	 * This function cannot be called when there is an outstanding AwaitPush().

   546 	 *

   547 	 * @param aRemoteHost	On return, the address of the remote host. Clients must pass 

   548 	 * 						in a reference to a NULL HBufC8 pointer. The function allocates a new HBufC8 

   549 	 * 						buffer to hold the address, and passes ownership of the buffer to the client.

   550 	 * @return				KErrNone on successful completion, KErrNotSupported if not implemented,

   551 	 * 						or one of the system error codes on failure.

   552 	 */

   553 	virtual TInt GetServerAddress(HBufC8*& aRemoteHost)=0;

   554 	

   555 protected: // methods

   556 	IMPORT_C CWapBoundCLPushService();

   557 	IMPORT_C void ConstructL();

   558 

   559 private: // ECOM

   560 	// D'tor Key identification required for ECOM

   561 	TUid iDtor_ID_Key;

   562 };

   563 

   564 /** Fully-Specified Connectionless Push

   565 */

   566 class CWapFullySpecCLPushService : public CBase

   567 /** 

   568 * Listens for WAP Push messages from a single, named remote host.

   569 * 

   570 * The class is an ECom plug-in interface. Clients use NewL() to request an implementation 

   571 * of the interface, and then call the interface's virtual functions to access 

   572 * the implementation's services. 

   573 * 

   574 * The use of the plug-in architecture allows different implementations to use 

   575 * different underlying WAP stacks.

   576 * 

   577 * Functions can return system wide error codes, and also API-specific errors 

   578 * as defined in wapmsgerr.h. 

   579 */

   580 {

   581 public: // creation/deletion

   582 	IMPORT_C static CWapFullySpecCLPushService* NewL();

   583 	IMPORT_C static CWapFullySpecCLPushService* NewL(const TUid& aImplementation);

   584 	IMPORT_C virtual ~CWapFullySpecCLPushService();

   585 

   586 public: // API methods

   587 

   588  	// Opens a socket which is to be used only with a single, named remote host.

   589 	/** 

   590 	* Connects to the WAP stack, opening an endpoint that can be used to listen for 

   591 	* Push messages from a specified remote host.

   592 	* 

   593 	* This overload of Connect() allows an IP address associated with a network 

   594 	* interface to be specified. In multihomed systems, this can be used to specify 

   595 	* the network interface to which the endpoint should be bound.

   596 	* 

   597 	* All CWapFullySpecCLPushService implementations must automatically close this 

   598 	* endpoint upon destruction.

   599 	* 

   600 	* @param aRemoteHost	The bearer-dependent address of the remote host with which 

   601 	* 						the data will be exchanged

   602 	* @param aRemotePort	The port on the remote host to which data will be sent

   603 	* @param aBearer		The bearer to listen on. You cannot use EAll.

   604 	* @param aSecure		Security flag to indicate whether WTLS should be used or not

   605 	* @param aInetAddr		The address of the adapter to use

   606 	* @return				KErrNone on successful completion, or one of the system error codes on failure. 

   607 	*/

   608 	virtual TInt Connect(const TDesC8& aRemoteHost, Wap::TPort aRemotePort, Wap::TBearer aBearer, TBool aSecure, TInetAddr aInetAddr)=0;

   609 

   610 	// Opens a socket which is to be used only with a single, named remote host.

   611 	/** 

   612 	* Connects to the WAP stack, opening an endpoint that can be used to listen for 

   613 	* Push messages from a specified remote host.

   614 	* 

   615 	* All CWapFullySpecCLPushService implementations must automatically close this 

   616 	* endpoint upon destruction.

   617 	* 

   618 	* @param aRemoteHost	The bearer-dependent address of the remote host with which 

   619 	* 						the data will be exchanged

   620 	* @param aRemotePort	The port on the remote host to which data will be sent

   621 	* @param aBearer		The bearer to listen on. You cannot use EAll.

   622 	* @param aSecure		Security flag to indicate whether WTLS should be used or not

   623 	* @return				KErrNone on successful completion, or one of the system error codes on failure. 

   624 	*/

   625 	virtual TInt Connect(const TDesC8& aRemoteHost, Wap::TPort aRemotePort, Wap::TBearer aBearer, TBool aSecure)=0;

   626 

   627 	/** 

   628 	* Requests an asynchronous notification upon arrival of the next push message 

   629 	* on the listening connection.

   630 	* 

   631 	* The request completes upon receipt of the message, filling the buffers with 

   632 	* as much received data as possible. A return code indicates whether further 

   633 	* data remains. The call must be re-issued for subsequent messages or to receive 

   634 	* remaining data from a previous push message.

   635 	* 

   636 	* @param aPushHeaders	A client-allocated buffer that, on completion, is filled 

   637 	* 						with the push message's header data

   638 	* @param aPushBody		A client-allocated buffer that, on completion, is filled with 

   639 	* 						the push message's body data

   640 	* @param aPushIdPckg	On completion, an integer ID that uniquely specifies the 

   641 	* 						push message

   642 	* @param aReqStatus		Asynchronous status word, used by the service provider to 

   643 	* 						notify the client when a push message has arrived.  

   644 	* 						EMoreData is returned if more pushed data is available.

   645 	* @return				KErrNone on successful completion, or one of the system error codes on failure. 

   646 	*/

   647 	virtual TInt AwaitPush(TDes8& aPushHeaders, TDes8& aPushBody, TPckgBuf<TUint8>& aPushIdPckg, TRequestStatus& aReqStatus)=0;

   648 

   649 	/** 

   650 	* Cancels a previous push message request.

   651 	* 

   652 	* If a push message arrives, the client will not be notified. 

   653 	*

   654 	*/

   655 	virtual void CancelAwaitPush()=0;

   656 

   657 

   658 	/** 

   659 	* Gets the local port of this endpoint.

   660 	* 

   661 	* This is useful if the port was chosen automatically. 

   662 	* 

   663 	* @param aPort	On return, the port number

   664 	* @return		KErrNone on successful completion, or one of the system error codes on failure. 

   665 	*/

   666 	virtual TInt GetLocalPort(Wap::TPort& aPort)=0;	// /// (out) the port number

   667 

   668 

   669 	/** 

   670 	* Gets the local address of this endpoint. 

   671 	* 

   672 	* @param aLocalHost	On return, the address of the local host. Clients must pass 

   673 	* 					in a reference to a NULL HBufC8 pointer. The function allocates a new HBufC8 

   674 	* 					buffer to hold the address, and passes ownership of the buffer to the client.

   675 	* @return			KErrNone on successful completion, or one of the system error codes on failure. 

   676 	*/

   677 	virtual TInt GetLocalAddress(HBufC8*& aLocalHost)=0;	// /// (out) the address of the local host

   678 

   679 protected: // methods

   680 	IMPORT_C CWapFullySpecCLPushService();

   681 	IMPORT_C void ConstructL();

   682 

   683 private: // ECOM

   684 	// D'tor Key identification required for ECOM

   685 	TUid iDtor_ID_Key;

   686 };

   687 

   688 /** Bound Connectionless WSP

   689 *  @released since v8.0

   690 */

   691 class CWapBoundCLWSPService : public CBase

   692 {

   693 public: // creation/deletion

   694 	IMPORT_C static CWapBoundCLWSPService* NewL();

   695 	IMPORT_C static CWapBoundCLWSPService* NewL(const TUid& aImplementation);

   696 	IMPORT_C virtual ~CWapBoundCLWSPService();

   697 

   698 public: // API methods

   699 

   700 	/** 

   701 	 * Connects to the WAP stack, opening an endpoint that can be used for S-Unit-MethodInvoke and 

   702 	 * S-Unit-MethodResult primitives.

   703 	 *

   704 	 * @param aBearer	The bearer to listen on (use EAll for all bearers)

   705 	 * @param aPort		The port to listen on. If set to 0, a local port will be chosen for the 

   706 	 *					client's first MethodInvoke()

   707 	 * @return			KErrNone on successful completion, or one of the system error codes on failure.

   708 	 */

   709 	virtual TInt Connect(Wap::TBearer aBearer,Wap::TPort aPort, TBool aSecure)=0;

   710 

   711 	/**

   712 	 * Sends a request to a remote endpoint.

   713 	 *

   714 	 * @param aBearer			The bearer to be used, if the bound connection was opened with EAll

   715 	 * @param aRemoteHost		The address of the remote host to which to send the request. 

   716 	 * 							The format of the address is bearer-specific.

   717 	 * @param aRemotePort		The port on the remote host to which the request will be sent

   718 	 * @param aMethod

   719 	 * @param aURI

   720 	 * @param aReqHeaders

   721 	 * @param aReqBody

   722 	 * @param aTransactionId

   723 	 * @return					KErrNone on successful completion, or one of the system error codes on failure.

   724 	 */ 

   725 	virtual TInt MethodInvoke(Wap::TBearer aBearer, const TDesC8& aRemoteHost, Wap::TPort aRemotePort, TUint aMethod, const TDesC& aURI, const TDesC8& aReqHeaders, const TDesC8& aReqBody, const TUint8 aTransactionId)=0;

   726 

   727 	/**

   728 	 * Waits for a datagram to be received.

   729 	 *

   730 	 * @param aReqHeaders

   731 	 * @param aReqBody

   732 	 * @param aTransactionIdPckg

   733 	 * @param aWspStatus

   734 	 * @param aReqStatus			Asynchonrous status word, used to signal when a data size is known

   735 	 * @param aTimeout

   736 	 * @return 						KErrNone on successful completion, or one of the system error codes on failure.

   737 	 */

   738 	virtual TInt MethodResult(TDes8& aReqHeaders, TDes8& aReqBody, TPckgBuf<TUint8>& aTransactionIdPckg, TWSPStatus& aWspStatus, TRequestStatus& aReqStatus, TUint32 aTimeout)=0;

   739 

   740 	/**

   741 	 * Cancels a previously requested asynchronous MethodResult() notification.

   742 	 * 

   743 	 * If a datagram arrives at the local host, it will be discarded.

   744 	 * 

   745 	 */	

   746 	virtual void CancelReq()=0;

   747 

   748 

   749 	/** 

   750 	 * Gets the local port of this endpoint.

   751 	 *

   752 	 * This is useful if the port was chosen automatically.

   753  	 * 

   754  	 * @param aPort	On return, the port number

   755 	 * @return		KErrNone on successful completion, or one of the system error codes on failure.

   756 	 */

   757 	virtual TInt GetLocalPort(Wap::TPort& aPort)=0;	// /// (out) the port number

   758 

   759 	/**

   760 	 * Gets the local address of this endpoint.

   761 	 * 

   762 	 * @param aLocalHost	On return, the address of the local host. Clients must pass 

   763 	 * 						in a reference to a NULL HBufC8 pointer. The function allocates a new HBufC8 

   764 	 * 						buffer to hold the address, and passes ownership of the buffer to the client.

   765 	 * @return				KErrNone on successful completion, or one of the system error codes on failure.

   766 	 */

   767 	virtual TInt GetLocalAddress(HBufC8*& aLocalHost)=0;	// /// (out) the address of the local host

   768 

   769 	/**

   770 	 * Gets the bearer on which a received datagram arrived.

   771 	 *

   772 	 * Useful when EAll was specified in Connect()

   773 	 *

   774 	 * @param aBearer	On return, the bearer

   775 	 * @return			KErrNone on successful completion, or one of the system error codes on failure.

   776 	 */

   777 	virtual TInt GetBearer(Wap::TBearer& /*aBearer*/)=0;

   778 	

   779 	/**

   780 	 * Gets the remote server address.

   781 	 * 

   782 	 * @param aServerAddress	On return, the address of the remote server. Clients must pass 

   783 	 * 							in a reference to a NULL HBufC8 pointer. The function allocates a new HBufC8 

   784 	 * 							buffer to hold the address, and passes ownership of the buffer to the client.

   785 	 * @return					KErrNone on successful completion, or one of the system error codes on failure.

   786 	 */

   787 	virtual TInt GetServerAddress(HBufC8*& aServerAddress)=0;	// /// (out) the address of the remote server

   788 	

   789 protected: // methods

   790 	IMPORT_C CWapBoundCLWSPService();

   791 	IMPORT_C void ConstructL();

   792 

   793 private: // ECOM

   794 	// D'tor Key identification required for ECOM

   795 	TUid iDtor_ID_Key;

   796 };

   797 

   798 /** 

   799 * Fully-Specified Connectionless WSP

   800 *  @released since v8.0

   801 */

   802 class CWapFullySpecCLWSPService : public CBase

   803 {

   804 public: // creation/deletion

   805 	IMPORT_C static CWapFullySpecCLWSPService* NewL();

   806 	IMPORT_C static CWapFullySpecCLWSPService* NewL(const TUid& aImplementation);

   807 	IMPORT_C virtual ~CWapFullySpecCLWSPService();

   808 

   809 public: // API methods

   810 

   811 	// Opens a socket which is to be used only with a single, named remote host.

   812 	/** 

   813 	* Connects to the WAP stack, opening an endpoint that can be used to listen for 

   814 	* Push messages from a specified remote host.

   815 	* 

   816 	* All CWapFullySpecCLWSPService implementations must automatically close this 

   817 	* endpoint upon destruction.

   818 	* 

   819 	* @param aRemoteHost	The bearer-dependent address of the remote host with which 

   820 	*						the data will be exchanged

   821 	* @param aRemotePort	The port on the remote host to which data will be sent

   822 	* @param aBearer		The bearer to listen on. You cannot use EAll.

   823 	* @param aSecure		Security flag to indicate whether WTLS should be used or not

   824 	* @return				KErrNone on successful completion, or one of the system error codes on failure. 

   825 	*/

   826 	virtual TInt Connect(const TDesC8& aRemoteHost, Wap::TPort aRemotePort, Wap::TBearer aBearer, TBool aSecure)=0;

   827 

   828 	/**

   829 	 * Sends a request to a remote endpoint.

   830 	 * 

   831 	 * @param aMethod

   832 	 * @param aURI

   833 	 * @param aReqHeaders

   834 	 * @param aReqBody

   835 	 * @param aTransactionId

   836 	 * @return					KErrNone on successful completion, or one of the system error codes on failure.

   837 	 */ 

   838 	virtual TInt MethodInvoke(TUint aMethod, const TDesC& aURI, const TDesC8& aReqHeaders, const TDesC8& aReqBody, TUint8 aTransactionId)=0;

   839 

   840 	/**

   841 	 * Waits for a datagram to be received

   842 	 * 

   843 	 * @param aReqHeaders

   844 	 * @param aReqBody

   845 	 * @param aTransactionIdPckg

   846 	 * @param aWspStatus

   847 	 * @param aReqStatus			Asynchonrous status word, used to signal when a data size is known

   848 	 * @param aTimeout

   849 	 * @return						KErrNone on successful completion, or one of the system error codes on failure.

   850 	 */

   851 	virtual TInt MethodResult(TDes8& aReqHeaders, TDes8& aReqBody, TPckgBuf<TUint8>& aTransactionIdPckg, TWSPStatus& aWspStatus, TRequestStatus& aReqStatus, TUint32 aTimeout)=0;

   852 

   853 

   854 	/**

   855 	 * Cancels a previously-requested MethodResult() notification. 

   856 	 *

   857 	 * If a message arrives the client will not be notified.

   858 	 * 

   859 	 */ 

   860 	virtual void CancelReq()=0;

   861 

   862 	/** 

   863 	 * Gets the local port of this endpoint.

   864 	 *

   865 	 * This is useful if the port was chosen automatically.

   866  	 * 

   867  	 * @param aPort	On return, the port number

   868 	 * @return		KErrNone on successful completion, or one of the system error codes on failure.

   869 	 */

   870 	virtual TInt GetLocalPort(Wap::TPort& aPort)=0;	// /// (out) the port number

   871 

   872 	/**

   873 	 * Gets the local address of this endpoint.

   874 	 *

   875 	 * @param aLocalHost	On return, the address of the local host. Clients must pass 

   876 	 * 						in a reference to a NULL HBufC8 pointer. The function allocates a new HBufC8 

   877 	 * 						buffer to hold the address, and passes ownership of the buffer to the client.

   878 	 * @return				KErrNone on successful completion, or one of the system error codes on failure.

   879 	 */

   880 	virtual TInt GetLocalAddress(HBufC8*& aLocalHost)=0;	// /// (out) the address of the local host

   881 	

   882 protected: // methods

   883 	IMPORT_C CWapFullySpecCLWSPService();

   884 	IMPORT_C void ConstructL();

   885 

   886 private: // ECOM

   887 	// D'tor Key identification required for ECOM

   888 	TUid iDtor_ID_Key;

   889 };

   890 

   891 

   892 // Utility class for client/implementation use.

   893 class CWapMessageUtils : public CBase

   894 /** Utility functions for use with WAP Messaging. */

   895 	{

   896 public:

   897 	// /// Return a list of all the addresses that are available

   898 	IMPORT_C static TInt GetLocalAddressesL(RArray<Wap::TAddressInfo>& aAddressInfo); 

   899 	};

   900 

   901 	

   902 #endif // __WAPMESSAGE_H__