epoc32/include/wapmessage.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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__