--- a/epoc32/include/mw/msenhostlet.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/mw/msenhostlet.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,152 @@
-msenhostlet.h
+/*
+* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* 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
+* which accompanies this distribution, and is available
+* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Hostlet call back interface
+*
+*/
+
+
+#ifndef M_SEN_HOSTLET_H
+#define M_SEN_HOSTLET_H
+
+// INCLUDES
+#include <e32base.h> // for CBase
+#include <badesca.h>
+
+#include <MSenHostletRequest.h>
+#include <MSenHostletResponse.h>
+#include <SenXmlServiceDescription.h>
+#include <SenServiceConnection.h>
+
+// FORWARD DECLARE
+
+// CLASS DECLARATION
+class MSenHostlet
+ {
+ public:
+ /**
+ * Main method for receiving incoming messages, which are typically SOAP / XML,
+ * and for providing service for these requests.
+ * @param aRequestUtf8 the request that needs to be be processed by the
+ * hostlet application (local service provider).
+ * @param aResponse is where response data is to be set.
+ * CSenHostletConnection::ResponsdL should be called
+ * in order to send the response back to the requester
+ * (service consumer).
+ */
+ virtual TInt ServiceL(MSenHostletRequest& aRequest, MSenHostletResponse& aResponse) = 0;
+
+ /**
+ * Defines the service endpoint for this hostlet
+ * @return endpoint that this hostlet has specified. If hostlet
+ * implementation does not wish to define any endpoint, but to
+ * use contract only, it should return KNullDesC8 (zero-length descriptor).
+ * In such case, CSenHostletConnection constructor will attempt to resolve
+ * secure identifier (UID3) of the application, and use that to generate
+ * a locally unique endpoint. If the UID3 is not available, then the
+ * constructor of CSenHostletConnection will leave with the following
+ * error code: KErrSenNoContractNoEndPoint
+ *
+ * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot
+ * create hostlet connection: instead, CSenHostletConnection constructor
+ * will leave with the following code: KErrSenNoContractNoEndPoint
+ *
+ * If endpoint is not specified, hostlet connection itself
+ * will generate an endpoint from applications secure ID (UID3) if such is available,
+ * and consumers can invoke the service via the provided contract ("service type"
+ * identifier).
+ *
+ */
+ virtual TPtrC8 Endpoint() const = 0;
+
+ /**
+ * Defines the service constract URI for this hostlet
+ * @return the URI identifier for the provided service, for example
+ * "urn:liberty:id-sis-pp:2003-08". Note that there might be multiple
+ * hostlets (local service providers) which all share common service
+ * type, that is, they all have same service contract URI.
+ *
+ * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot
+ * create hostlet connection: instead, CSenHostletConnection constructor
+ * will leave with the following error code: KErrSenNoContractNoEndPoint
+ */
+ virtual TPtrC8 Contract() const = 0;
+
+ /**
+ * Defines the framework for this hostlet.
+ * @return the framework ID. Default inline implementation
+ * returns RESTful service invocation framework ID,
+ * KDefaultRestServicesFrameworkID, as defined in SenServiceConnection.h
+ */
+ inline virtual TPtrC8 FrameworkId() const { return KDefaultRestServicesFrameworkID(); }
+
+ /**
+ * Each Hostlet implementation may further describes its service via this callback.
+ * @param aSD is the description, where service specific attributes can be defined.
+ * Default, inline implementation sets the endpoint, contract and framework ID
+ * by calling the other, more simple callbacks.
+ *
+ * It is mandatory for each hostlet to define either endpoint or contract.
+ * Otherwise, the constuctor of CSenHostletConnection will leave with the
+ * following error code:
+ * KErrSenNoContractNoEndPoint - neither endpoint or contract was
+ * specified. This is illegal, since the service would lack an identifier.
+ *
+ * @param aSD is the service description into which this hostlet may further
+ * define other service specific information, like facets. Note that this
+ * call back is "stronger" than Endpoint() and Contract(), and thus any
+ * value specified in this method will be in effect for the hostlet connection.
+ */
+ inline virtual void DescribeServiceL(CSenXmlServiceDescription& aSD)
+ {
+ aSD.SetEndPointL(Endpoint());
+ aSD.SetContractL(Contract());
+ aSD.SetFrameworkIdL(FrameworkId());
+ }
+
+ /**
+ * This callback function is invoked each time when any hostlet connection's
+ * asynchronous RespondL is completed. Method can be used to trigger the
+ * release of some response releated system resources, as it is invoked
+ * after the response has been delivered to the consumer (application
+ * may wish to close handles to reserved file or memory).
+ *
+ * @param aTxnId identifies what transaction (service message) was completed
+ * @param aCompletionCode indicates whether transaction completed ok (KErrNone)
+ * or not (error code).
+ * @param aDesc may provide additional information about completed transaction,
+ * typically this description is provided, if an error has occured.
+ * It is optional for hostlet implementation to implement this method.
+ */
+ inline virtual void OnServiceCompleteL(TInt /* aTxnId */,
+ TInt /* aCompletionCode */,
+ const TDesC8& /* aDesc*/ ) { ; }
+
+ /**
+ * Hostlet connection calls this method several times, passing a different
+ * UID per each call. If application wants to provide particular interface
+ * to hostlet connection (web services stack), it needs to return a pointer
+ * to such M-class as a return value of this method. For any interface, that
+ * application has not implemented, it is supposed to return NULL.
+ * @param aUID is the unique identifier of some interface
+ * @return value should be a valid (void) pointer to any interface implemented
+ * by the application. NULL signalizes that application does not provide interface
+ * for give UID.
+ */
+ inline virtual TAny* GetInterfaceByUid( TUid /* aUID */ ) { return NULL; };
+ };
+
+
+#endif // M_SEN_HOSTLET_H
+
+// End of File