diff -r 000000000000 -r 094583676ce7 IMPSengine/enginc/ImpsDataChannelAPI.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/IMPSengine/enginc/ImpsDataChannelAPI.h Thu Dec 17 08:41:52 2009 +0200 @@ -0,0 +1,182 @@ +/* +* Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: This file defines an interface for sending and receiving data +* from transport module. In other words a transport module must +* provide the methods defined below and call the observer methods +* for incoming data. +* +* +*/ + +#ifndef WV_DATACHANNEL_API_H +#define WV_DATACHANNEL_API_H + +// CLASS DECLARATIONS + +/** +* MImpsDataReceiver +* +* Abstract interface for handling responses from data channel module. +* Server implements this class and gives a pointer to the data channel. +* Data channel module calls the method when it has received data. +*/ + +class MImpsDataReceiver + { + + public: // New functions + + /** + * Callback for transport request response + * This handles the responses to the SendL() method from MImpsSender + * + * NOTE: It is very important to bear in mind that the memory + * area which the fourth parameter points to, MUST be + * deallocated by the object that implements this abstract + * interface! After the IMPS Data Channel component has + * called this method, it is no longer responsible for + * maintenance (including deallocation) of this chunk of + * heap. Failure to free the memory area will result in + * a serious memory leak and, consequently, a crash. + * Also note that in many error cases, including a request + * timing out, the pointer will be NULL as there is no data + * to relay. + * + * @param TInt Operation-id given in SendL() method + * @param TInt Internal error code, KErrNone if successful + * @param TInt HTTP status code, 200 if successful + * @param HBufC8* Pointer to the raw eight-bit CSP data; + * must be deleted by the implementing class + * after its contents are no longer needed + */ + virtual void TransportResponse( const TInt aId, + const TInt aError, + const TInt aHttpStatus, + HBufC8* aCspMessage ) = 0; + }; + +/** +* MImpsSender +* +* Abstract interface for sending messages to the data channel. +* The data channel module implements this class. +*/ + +//The bearer connection manager used by MImpsSender instances +class MMsgConnManager; + +class MImpsSender + { + + public: // New functions + + /** + * Opens a session to the HTTP Stack. + * - If already opened then error code is returned ( KErrAlreadyExists ) + * - Leaves with KImpsErrorBearerSuspended if GPRS is suspended + * - KErrOutOfMemory if new objects cannot be allocated + * (- some other system-wide error code returned by the HTTP framework) + * + * This is a synchronous method: after a call to this method, the client + * application can assume the data channel to be open - provided the + * method call did not leave. + * + * @param aSAP WV SAP. + * The address has a format: + * hostport [ "/" hpath [ "?" search ]] + * Refer to RFC1738 + * @return void + */ + virtual void OpenL( const TDesC& aSAP ) = 0; + + /** + * Closes the session to HTTP Stack + * @return Status code of the performed operation. + */ + virtual void Close() = 0; + + /** + * Send a request. + * When this method returns the data is saved and aMessage + * parameter can be re-used. + * If the state of the bearer connection is other than + * EImpsBearerActive, leaves with an error immediately: + * * EImpsBearerLost state - KImpsErrorBearerNotReady + * * EImpsBearerSuspended state - KImpsErrorBearerSuspended + * The function may also leave with KImpsErrorSessionNotOpen + * in case OpenL() has not been called prior to the call of this method. + * + * A response is received through MImpsReceiver. + * The third parameter, aExpiryTime is optional. The function + * first checks whether the value is something other than 0. If + * it is, a timer gets instantiated and activated, and expires + * according to the value passed in the parameter. The + * value should be presented in seconds. + * + * @param aId operation-id to identify the request. + * @param aMessage data to be sent + * @param aExpiryTime expiry time of the request in seconds + */ + virtual void SendL( const TInt aId, + const TDesC8& aMessage, + const TInt aExpiryTime = 0 ) = 0; + + /** + * Destructor. A simple wrapper to the C++ destructor. + * + * NOTE that HTTP Stack uses the connection and socket + * server instances owned by MImpsConnectionManager, + * so one should be very careful NOT to Destroy() the + * ConnMan instance before an instance of this interface. + * At deletion time HTTP Stack might have outstanding socket + * reads and/or writes, the cancelling of which will surely + * fail in case the socket session on which the sockets were + * initially opened has been prematurely closed. + */ + virtual void Destroy() = 0; + + /** + * Cancel all pending transactions. + * After this request it is guaranteed that observer methods + * are not called until new requests have been made. + */ + virtual void CancelAll() = 0; + + /** + * Cancel a named transaction. + */ + virtual void CancelTransaction( const TInt aTID ) = 0; + + /** + * Return the number of requests to which + * a response has not yet been received. + */ + virtual TInt PendingRequests() const = 0; + + }; + +/** +* Creates a new sender object +* @param RFs& aSession Reference to an opened file session +* @param TDesC8& aMimeType MIME type of the messages to be sent +* @param MImpsReceiver* aReceiver Pointer to the receiving object +* @return MImpsSender +*/ +IMPORT_C MImpsSender* NewImpsSenderL( MImpsDataReceiver& aReceiver, + MMsgConnManager& aConnManager, + const TDesC8& aMimeType ); + +#endif // ?INCLUDE_H + +// End of File