1.1 --- a/epoc32/include/mw/msenhostlet.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/msenhostlet.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,152 @@
1.4 -msenhostlet.h
1.5 +/*
1.6 +* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Hostlet call back interface
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef M_SEN_HOSTLET_H
1.24 +#define M_SEN_HOSTLET_H
1.25 +
1.26 +// INCLUDES
1.27 +#include <e32base.h> // for CBase
1.28 +#include <badesca.h>
1.29 +
1.30 +#include <MSenHostletRequest.h>
1.31 +#include <MSenHostletResponse.h>
1.32 +#include <SenXmlServiceDescription.h>
1.33 +#include <SenServiceConnection.h>
1.34 +
1.35 +// FORWARD DECLARE
1.36 +
1.37 +// CLASS DECLARATION
1.38 +class MSenHostlet
1.39 + {
1.40 + public:
1.41 + /**
1.42 + * Main method for receiving incoming messages, which are typically SOAP / XML,
1.43 + * and for providing service for these requests.
1.44 + * @param aRequestUtf8 the request that needs to be be processed by the
1.45 + * hostlet application (local service provider).
1.46 + * @param aResponse is where response data is to be set.
1.47 + * CSenHostletConnection::ResponsdL should be called
1.48 + * in order to send the response back to the requester
1.49 + * (service consumer).
1.50 + */
1.51 + virtual TInt ServiceL(MSenHostletRequest& aRequest, MSenHostletResponse& aResponse) = 0;
1.52 +
1.53 + /**
1.54 + * Defines the service endpoint for this hostlet
1.55 + * @return endpoint that this hostlet has specified. If hostlet
1.56 + * implementation does not wish to define any endpoint, but to
1.57 + * use contract only, it should return KNullDesC8 (zero-length descriptor).
1.58 + * In such case, CSenHostletConnection constructor will attempt to resolve
1.59 + * secure identifier (UID3) of the application, and use that to generate
1.60 + * a locally unique endpoint. If the UID3 is not available, then the
1.61 + * constructor of CSenHostletConnection will leave with the following
1.62 + * error code: KErrSenNoContractNoEndPoint
1.63 + *
1.64 + * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot
1.65 + * create hostlet connection: instead, CSenHostletConnection constructor
1.66 + * will leave with the following code: KErrSenNoContractNoEndPoint
1.67 + *
1.68 + * If endpoint is not specified, hostlet connection itself
1.69 + * will generate an endpoint from applications secure ID (UID3) if such is available,
1.70 + * and consumers can invoke the service via the provided contract ("service type"
1.71 + * identifier).
1.72 + *
1.73 + */
1.74 + virtual TPtrC8 Endpoint() const = 0;
1.75 +
1.76 + /**
1.77 + * Defines the service constract URI for this hostlet
1.78 + * @return the URI identifier for the provided service, for example
1.79 + * "urn:liberty:id-sis-pp:2003-08". Note that there might be multiple
1.80 + * hostlets (local service providers) which all share common service
1.81 + * type, that is, they all have same service contract URI.
1.82 + *
1.83 + * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot
1.84 + * create hostlet connection: instead, CSenHostletConnection constructor
1.85 + * will leave with the following error code: KErrSenNoContractNoEndPoint
1.86 + */
1.87 + virtual TPtrC8 Contract() const = 0;
1.88 +
1.89 + /**
1.90 + * Defines the framework for this hostlet.
1.91 + * @return the framework ID. Default inline implementation
1.92 + * returns RESTful service invocation framework ID,
1.93 + * KDefaultRestServicesFrameworkID, as defined in SenServiceConnection.h
1.94 + */
1.95 + inline virtual TPtrC8 FrameworkId() const { return KDefaultRestServicesFrameworkID(); }
1.96 +
1.97 + /**
1.98 + * Each Hostlet implementation may further describes its service via this callback.
1.99 + * @param aSD is the description, where service specific attributes can be defined.
1.100 + * Default, inline implementation sets the endpoint, contract and framework ID
1.101 + * by calling the other, more simple callbacks.
1.102 + *
1.103 + * It is mandatory for each hostlet to define either endpoint or contract.
1.104 + * Otherwise, the constuctor of CSenHostletConnection will leave with the
1.105 + * following error code:
1.106 + * KErrSenNoContractNoEndPoint - neither endpoint or contract was
1.107 + * specified. This is illegal, since the service would lack an identifier.
1.108 + *
1.109 + * @param aSD is the service description into which this hostlet may further
1.110 + * define other service specific information, like facets. Note that this
1.111 + * call back is "stronger" than Endpoint() and Contract(), and thus any
1.112 + * value specified in this method will be in effect for the hostlet connection.
1.113 + */
1.114 + inline virtual void DescribeServiceL(CSenXmlServiceDescription& aSD)
1.115 + {
1.116 + aSD.SetEndPointL(Endpoint());
1.117 + aSD.SetContractL(Contract());
1.118 + aSD.SetFrameworkIdL(FrameworkId());
1.119 + }
1.120 +
1.121 + /**
1.122 + * This callback function is invoked each time when any hostlet connection's
1.123 + * asynchronous RespondL is completed. Method can be used to trigger the
1.124 + * release of some response releated system resources, as it is invoked
1.125 + * after the response has been delivered to the consumer (application
1.126 + * may wish to close handles to reserved file or memory).
1.127 + *
1.128 + * @param aTxnId identifies what transaction (service message) was completed
1.129 + * @param aCompletionCode indicates whether transaction completed ok (KErrNone)
1.130 + * or not (error code).
1.131 + * @param aDesc may provide additional information about completed transaction,
1.132 + * typically this description is provided, if an error has occured.
1.133 + * It is optional for hostlet implementation to implement this method.
1.134 + */
1.135 + inline virtual void OnServiceCompleteL(TInt /* aTxnId */,
1.136 + TInt /* aCompletionCode */,
1.137 + const TDesC8& /* aDesc*/ ) { ; }
1.138 +
1.139 + /**
1.140 + * Hostlet connection calls this method several times, passing a different
1.141 + * UID per each call. If application wants to provide particular interface
1.142 + * to hostlet connection (web services stack), it needs to return a pointer
1.143 + * to such M-class as a return value of this method. For any interface, that
1.144 + * application has not implemented, it is supposed to return NULL.
1.145 + * @param aUID is the unique identifier of some interface
1.146 + * @return value should be a valid (void) pointer to any interface implemented
1.147 + * by the application. NULL signalizes that application does not provide interface
1.148 + * for give UID.
1.149 + */
1.150 + inline virtual TAny* GetInterfaceByUid( TUid /* aUID */ ) { return NULL; };
1.151 + };
1.152 +
1.153 +
1.154 +#endif // M_SEN_HOSTLET_H
1.155 +
1.156 +// End of File