1 // Copyright (c) 2001-2010 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 #ifndef __WAPMESSAGE_H__

    17 #define __WAPMESSAGE_H__

    18 

    19 

    20 #include <e32base.h>

    21 #include <e32std.h>

    22 #include <in_sock.h>

    23 

    24 /** 

    25 * @file

    26 *

    27 * The WAP Messaging API.  

    28 *

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

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

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

    32 *

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

    34 * errors, with some returning additional specific errors.

    35 *

    36 * @publishedAll

    37 * @released since v7.0

    38 */

    39 

    40 /** 

    41 * Defines WAP-related types and error codes. 

    42 */

    43 namespace Wap

    44 	{

    45 	// Bearer type definition

    46 	typedef enum

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

    48 		{

    49 		/** All bearers. */

    50 		EAll,

    51 		/** Internet Protocol. */

    52 		EIP,

    53 		/** 7-bit SMS. */

    54 		ESMS7,

    55 		/** 8-bit SMS. */

    56 		ESMS,

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

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

    59 		EWAPSMS7,

    60 		/** 8-bit SMS. */

    61 		EWAPSMS

    62 		} TBearer;

    63 

    64 	// Port number definition

    65 	/** A port number. */

    66 	typedef TUint16 TPort;

    67  

    68 	class TAddressInfo

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

    70 		{

    71 	public:

    72 		/** Interface name. */

    73 		TName iName;

    74 		/** Interface IP address. */

    75 		TInetAddr iAddress;

    76 		};

    77 	}

    78 

    79 

    80 /**

    81 * The WSP status type definition.

    82 * @internalComponent

    83 */

    84 typedef TUint8 TWSPStatus;

    85 	

    86 /** Bound WDP */

    87 class CWapBoundDatagramService : public CBase

    88 /** 

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

    90 *

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

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

    93 * the implementation's services. 

    94 *

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

    96 * different underlying WAP stacks.

    97 *

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

    99 * as defined in wapmsgerr.h. 

   100 * 

   101 */

   102 	{

   103 public: // creation/deletion

   104 	IMPORT_C static CWapBoundDatagramService* NewL();

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

   106 	IMPORT_C virtual ~CWapBoundDatagramService();

   107 

   108 public: // API methods

   109 

   110 	/** 

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

   112 	* subsequent incoming datagrams.

   113 	*

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

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

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

   117 	* 

   118 	* All CWapBoundDatagramService implementations must automatically close this 

   119 	* endpoint upon destruction.

   120 	* 

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

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

   123 	* 					for the client's first SendTo()

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

   125 	*					in a multihomed system.

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

   127 	* 					on failure.

   128 	*/

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

   130 

   131 	/** 

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

   133 	* subsequent incoming datagrams.

   134 	* 

   135 	* All CWapBoundDatagramService implementations must automatically close this 

   136 	* endpoint upon destruction. 

   137 	* 

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

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

   140 	* 					for the client's first SendTo()

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

   142 	* 					on failure.

   143 	*/

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

   145 

   146 	/** Sends data to a remote endpoint. 

   147 	* 

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

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

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

   151 	* @param aBuffer		The data buffer to be sent

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

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

   154 	* 						on failure.

   155 	*/

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

   157 

   158 	/** 

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

   160 	* to retrieve it.

   161 	* 

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

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

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

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

   166 	* fully. 

   167 	* 

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

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

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

   171 	* 						on failure.

   172 	*/

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

   174 

   175 	/** 

   176 	* Receives data on a bound port. 

   177 	* 

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

   179 	* 

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

   181 	* 						host from which the data was received

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

   183 	* 						data was received

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

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

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

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

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

   189 	* 						a datagram was received

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

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

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

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

   194 	*/

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

   196 							TRequestStatus& aReqStatus, TUint32 aTimeout)=0;

   197  

   198 	/** 

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

   200 	*

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

   202 	* 

   203 	*/

   204 	virtual void CancelRecv()=0;

   205 

   206 	/** 

   207 	* Gets the local port of this endpoint.

   208 	* 

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

   210 	* 

   211 	* @param aPort	On return, the port number

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

   213 	*/

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

   215 

   216 	/** 

   217 	* Gets the local address of this endpoint. 

   218 	* 

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

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

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

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

   223 	*/

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

   225 

   226 	/** 

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

   228 	* 

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

   230 	* 

   231 	* @param aBearer	On return, the bearer

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

   233 	*/

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

   235 

   236 	/** 

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

   238 	*

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

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

   241 	* 

   242 	* The function will fail for a stream connection.

   243 	*

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

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

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

   247 	*						on failure.

   248 	*/	

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

   250 	

   251 protected: // methods

   252 	IMPORT_C CWapBoundDatagramService();

   253 	IMPORT_C void ConstructL();

   254 

   255 private: // attributes

   256 	// D'tor Key identification required for ECOM

   257 	TUid iDtor_ID_Key;

   258 	};

   259 

   260 /** Fully-Specified WDP

   261 */

   262 class CWapFullySpecDatagramService : public CBase

   263 /** 

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

   265 * named remote host.

   266 * 

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

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

   269 * the implementation's services. 

   270 * 

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

   272 * different underlying WAP stacks.

   273 * 

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

   275 * as defined in wapmsgerr.h. 

   276 */

   277 	{

   278 public: // creation/deletion

   279 	IMPORT_C static CWapFullySpecDatagramService* NewL();

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

   281 	IMPORT_C virtual ~CWapFullySpecDatagramService();

   282 

   283 public: // API methods

   284 

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

   286 	/** 

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

   288 	* subsequent incoming datagrams.

   289 	*	

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

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

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

   293 	* 

   294 	* All CWapFullySpecDatagramService implementations must automatically close 

   295 	* this endpoint upon destruction.

   296 	* 

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

   298 	* 						the data will be exchanged

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

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

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

   302 	* 						in a multihomed system.

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

   304 	*/

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

   306 

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

   308 	/** 

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

   310 	* subsequent incoming datagrams.

   311 	* 

   312 	* All CWapFullySpecDatagramService implementations must automatically close 

   313 	* this endpoint upon destruction.

   314 	* 

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

   316 	* 						the data will be exchanged

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

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

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

   320 	*/

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

   322 

   323 	/** 

   324 	* Sends data on a fully-specified connection.

   325 	* 

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

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

   328 	*/

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

   330 

   331 	/** 

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

   333 	* to retrieve it.

   334 	* 

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

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

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

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

   339 	* fully. 

   340 	* 

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

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

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

   344 	*/

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

   346 

   347 	/** 

   348 	* Receives data on a bound port. 

   349 	* 

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

   351 	* 

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

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

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

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

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

   357 	* 					a datagram was received

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

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

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

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

   362 	*/

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

   364 

   365 	/** 

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

   367 	* 

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

   369 	* 

   370 	*/

   371 	virtual void CancelRecv()=0;

   372 

   373 	/** 

   374 	* Gets the local port of this endpoint.

   375 	* 

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

   377 	* 

   378 	* @param aPort	On return, the port number

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

   380 	*/

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

   382 

   383 	/** 

   384 	* Gets the local address of this endpoint. 

   385 	* 

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

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

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

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

   390 	*/

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

   392 

   393 	/** 

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

   395 	* 

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

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

   398 	* 

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

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

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

   402 	*/

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

   404 	

   405 protected: // methods

   406 	IMPORT_C CWapFullySpecDatagramService();

   407 	IMPORT_C void ConstructL();

   408 

   409 private: // ECOM

   410 	// D'tor Key identification required for ECOM

   411 	TUid iDtor_ID_Key;

   412 	};

   413 

   414 /** Bound Connectionless Push

   415 */

   416 class CWapBoundCLPushService : public CBase

   417 /** 

   418 * Listens for WAP Push messages from any sender.

   419 * 

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

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

   422 * the implementation's services. 

   423 * 

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

   425 * different underlying WAP stacks.

   426 * 

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

   428 * as defined in wapmsgerr.h. 

   429 * 

   430 */

   431 {

   432 public: // creation/deletion

   433 	IMPORT_C static CWapBoundCLPushService* NewL();

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

   435 	IMPORT_C virtual ~CWapBoundCLPushService();

   436 

   437 public: // API methods

   438 

   439 	

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

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

   442 	/** 

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

   444 	* Push messages from any sender.

   445 	* 

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

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

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

   449 	* 

   450 	* All CWapBoundCLPushService implementations must automatically close this endpoint 

   451 	* upon destruction.

   452 	* 

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

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

   455 	* 					for the client's first SendTo()

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

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

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

   459 	*/

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

   461 

   462 	

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

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

   465 	/** 

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

   467 	* Push messages from any sender.

   468 	* 

   469 	* All CWapBoundCLPushService implementations must automatically close this endpoint 

   470 	* upon destruction.

   471 	* 

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

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

   474 	* 					for the client's first SendTo()

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

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

   477 	*/

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

   479 

   480 	/** 

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

   482 	* on the listening connection.

   483 	* 

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

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

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

   487 	* remaining data from a previous push message.

   488 	* 

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

   490 	* 						with the push message's header data

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

   492 	* 						the push message's body data

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

   494 	* 						push message

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

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

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

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

   499 	*/

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

   501 

   502 	/** 

   503 	* Cancels a previous push message request.

   504 	* 

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

   506 	*

   507 	*/

   508 	virtual void CancelAwaitPush()=0;

   509 

   510 	/** 

   511 	* Gets the local port of this endpoint.

   512 	* 

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

   514 	* 

   515 	* @param aPort	On return, the port number

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

   517 	*/

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

   519 

   520 	/** 

   521 	* Gets the local address of this endpoint. 

   522 	* 

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

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

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

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

   527 	*/

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

   529 

   530 	/** 

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

   532 	* 

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

   534 	* 

   535 	* @param aBearer	On return, the bearer

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

   537 	*/

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

   539 

   540 	/**

   541 	 * Gets the address of the remote server.

   542 	 *

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

   544 	 *

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

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

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

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

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

   550 	 */

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

   552 	

   553 protected: // methods

   554 	IMPORT_C CWapBoundCLPushService();

   555 	IMPORT_C void ConstructL();

   556 

   557 private: // ECOM

   558 	// D'tor Key identification required for ECOM

   559 	TUid iDtor_ID_Key;

   560 };

   561 

   562 /** Fully-Specified Connectionless Push

   563 */

   564 class CWapFullySpecCLPushService : public CBase

   565 /** 

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

   567 * 

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

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

   570 * the implementation's services. 

   571 * 

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

   573 * different underlying WAP stacks.

   574 * 

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

   576 * as defined in wapmsgerr.h. 

   577 */

   578 {

   579 public: // creation/deletion

   580 	IMPORT_C static CWapFullySpecCLPushService* NewL();

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

   582 	IMPORT_C virtual ~CWapFullySpecCLPushService();

   583 

   584 public: // API methods

   585 

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

   587 	/** 

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

   589 	* Push messages from a specified remote host.

   590 	* 

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

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

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

   594 	* 

   595 	* All CWapFullySpecCLPushService implementations must automatically close this 

   596 	* endpoint upon destruction.

   597 	* 

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

   599 	* 						the data will be exchanged

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

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

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

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

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

   605 	*/

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

   607 

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

   609 	/** 

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

   611 	* Push messages from a specified remote host.

   612 	* 

   613 	* All CWapFullySpecCLPushService implementations must automatically close this 

   614 	* endpoint upon destruction.

   615 	* 

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

   617 	* 						the data will be exchanged

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

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

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

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

   622 	*/

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

   624 

   625 	/** 

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

   627 	* on the listening connection.

   628 	* 

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

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

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

   632 	* remaining data from a previous push message.

   633 	* 

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

   635 	* 						with the push message's header data

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

   637 	* 						the push message's body data

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

   639 	* 						push message

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

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

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

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

   644 	*/

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

   646 

   647 	/** 

   648 	* Cancels a previous push message request.

   649 	* 

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

   651 	*

   652 	*/

   653 	virtual void CancelAwaitPush()=0;

   654 

   655 

   656 	/** 

   657 	* Gets the local port of this endpoint.

   658 	* 

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

   660 	* 

   661 	* @param aPort	On return, the port number

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

   663 	*/

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

   665 

   666 

   667 	/** 

   668 	* Gets the local address of this endpoint. 

   669 	* 

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

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

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

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

   674 	*/

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

   676 

   677 protected: // methods

   678 	IMPORT_C CWapFullySpecCLPushService();

   679 	IMPORT_C void ConstructL();

   680 

   681 private: // ECOM

   682 	// D'tor Key identification required for ECOM

   683 	TUid iDtor_ID_Key;

   684 };

   685 

   686 /** Bound Connectionless WSP

   687 *  @released since v8.0

   688 */

   689 class CWapBoundCLWSPService : public CBase

   690 {

   691 public: // creation/deletion

   692 	IMPORT_C static CWapBoundCLWSPService* NewL();

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

   694 	IMPORT_C virtual ~CWapBoundCLWSPService();

   695 

   696 public: // API methods

   697 

   698 	/** 

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

   700 	 * S-Unit-MethodResult primitives.

   701 	 *

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

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

   704 	 *					client's first MethodInvoke()

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

   706 	 */

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

   708 

   709 	/**

   710 	 * Sends a request to a remote endpoint.

   711 	 *

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

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

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

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

   716 	 * @param aMethod

   717 	 * @param aURI

   718 	 * @param aReqHeaders

   719 	 * @param aReqBody

   720 	 * @param aTransactionId

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

   722 	 */ 

   723 	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;

   724 

   725 	/**

   726 	 * Waits for a datagram to be received.

   727 	 *

   728 	 * @param aReqHeaders

   729 	 * @param aReqBody

   730 	 * @param aTransactionIdPckg

   731 	 * @param aWspStatus

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

   733 	 * @param aTimeout

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

   735 	 */

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

   737 

   738 	/**

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

   740 	 * 

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

   742 	 * 

   743 	 */	

   744 	virtual void CancelReq()=0;

   745 

   746 

   747 	/** 

   748 	 * Gets the local port of this endpoint.

   749 	 *

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

   751  	 * 

   752  	 * @param aPort	On return, the port number

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

   754 	 */

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

   756 

   757 	/**

   758 	 * Gets the local address of this endpoint.

   759 	 * 

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

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

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

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

   764 	 */

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

   766 

   767 	/**

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

   769 	 *

   770 	 * Useful when EAll was specified in Connect()

   771 	 *

   772 	 * @param aBearer	On return, the bearer

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

   774 	 */

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

   776 	

   777 	/**

   778 	 * Gets the remote server address.

   779 	 * 

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

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

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

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

   784 	 */

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

   786 	

   787 protected: // methods

   788 	IMPORT_C CWapBoundCLWSPService();

   789 	IMPORT_C void ConstructL();

   790 

   791 private: // ECOM

   792 	// D'tor Key identification required for ECOM

   793 	TUid iDtor_ID_Key;

   794 };

   795 

   796 /** 

   797 * Fully-Specified Connectionless WSP

   798 *  @released since v8.0

   799 */

   800 class CWapFullySpecCLWSPService : public CBase

   801 {

   802 public: // creation/deletion

   803 	IMPORT_C static CWapFullySpecCLWSPService* NewL();

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

   805 	IMPORT_C virtual ~CWapFullySpecCLWSPService();

   806 

   807 public: // API methods

   808 

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

   810 	/** 

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

   812 	* Push messages from a specified remote host.

   813 	* 

   814 	* All CWapFullySpecCLWSPService implementations must automatically close this 

   815 	* endpoint upon destruction.

   816 	* 

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

   818 	*						the data will be exchanged

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

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

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

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

   823 	*/

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

   825 

   826 	/**

   827 	 * Sends a request to a remote endpoint.

   828 	 * 

   829 	 * @param aMethod

   830 	 * @param aURI

   831 	 * @param aReqHeaders

   832 	 * @param aReqBody

   833 	 * @param aTransactionId

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

   835 	 */ 

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

   837 

   838 	/**

   839 	 * Waits for a datagram to be received

   840 	 * 

   841 	 * @param aReqHeaders

   842 	 * @param aReqBody

   843 	 * @param aTransactionIdPckg

   844 	 * @param aWspStatus

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

   846 	 * @param aTimeout

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

   848 	 */

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

   850 

   851 

   852 	/**

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

   854 	 *

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

   856 	 * 

   857 	 */ 

   858 	virtual void CancelReq()=0;

   859 

   860 	/** 

   861 	 * Gets the local port of this endpoint.

   862 	 *

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

   864  	 * 

   865  	 * @param aPort	On return, the port number

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

   867 	 */

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

   869 

   870 	/**

   871 	 * Gets the local address of this endpoint.

   872 	 *

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

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

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

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

   877 	 */

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

   879 	

   880 protected: // methods

   881 	IMPORT_C CWapFullySpecCLWSPService();

   882 	IMPORT_C void ConstructL();

   883 

   884 private: // ECOM

   885 	// D'tor Key identification required for ECOM

   886 	TUid iDtor_ID_Key;

   887 };

   888 

   889 

   890 // Utility class for client/implementation use.

   891 class CWapMessageUtils : public CBase

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

   893 	{

   894 public:

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

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

   897 	};

   898 

   899 	

   900 #endif // __WAPMESSAGE_H__