2 * Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of "Eclipse Public License v1.0"
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: Hostlet call back interface
19 #ifndef M_SEN_HOSTLET_H
20 #define M_SEN_HOSTLET_H
23 #include <e32base.h> // for CBase
26 #include <MSenHostletRequest.h>
27 #include <MSenHostletResponse.h>
28 #include <SenXmlServiceDescription.h>
29 #include <SenServiceConnection.h>
38 * Main method for receiving incoming messages, which are typically SOAP / XML,
39 * and for providing service for these requests.
40 * @param aRequestUtf8 the request that needs to be be processed by the
41 * hostlet application (local service provider).
42 * @param aResponse is where response data is to be set.
43 * CSenHostletConnection::ResponsdL should be called
44 * in order to send the response back to the requester
47 virtual TInt ServiceL(MSenHostletRequest& aRequest, MSenHostletResponse& aResponse) = 0;
50 * Defines the service endpoint for this hostlet
51 * @return endpoint that this hostlet has specified. If hostlet
52 * implementation does not wish to define any endpoint, but to
53 * use contract only, it should return KNullDesC8 (zero-length descriptor).
54 * In such case, CSenHostletConnection constructor will attempt to resolve
55 * secure identifier (UID3) of the application, and use that to generate
56 * a locally unique endpoint. If the UID3 is not available, then the
57 * constructor of CSenHostletConnection will leave with the following
58 * error code: KErrSenNoContractNoEndPoint
60 * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot
61 * create hostlet connection: instead, CSenHostletConnection constructor
62 * will leave with the following code: KErrSenNoContractNoEndPoint
64 * If endpoint is not specified, hostlet connection itself
65 * will generate an endpoint from applications secure ID (UID3) if such is available,
66 * and consumers can invoke the service via the provided contract ("service type"
70 virtual TPtrC8 Endpoint() const = 0;
73 * Defines the service constract URI for this hostlet
74 * @return the URI identifier for the provided service, for example
75 * "urn:liberty:id-sis-pp:2003-08". Note that there might be multiple
76 * hostlets (local service providers) which all share common service
77 * type, that is, they all have same service contract URI.
79 * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot
80 * create hostlet connection: instead, CSenHostletConnection constructor
81 * will leave with the following error code: KErrSenNoContractNoEndPoint
83 virtual TPtrC8 Contract() const = 0;
86 * Defines the framework for this hostlet.
87 * @return the framework ID. Default inline implementation
88 * returns RESTful service invocation framework ID,
89 * KDefaultRestServicesFrameworkID, as defined in SenServiceConnection.h
91 inline virtual TPtrC8 FrameworkId() const { return KDefaultRestServicesFrameworkID(); }
94 * Each Hostlet implementation may further describes its service via this callback.
95 * @param aSD is the description, where service specific attributes can be defined.
96 * Default, inline implementation sets the endpoint, contract and framework ID
97 * by calling the other, more simple callbacks.
99 * It is mandatory for each hostlet to define either endpoint or contract.
100 * Otherwise, the constuctor of CSenHostletConnection will leave with the
101 * following error code:
102 * KErrSenNoContractNoEndPoint - neither endpoint or contract was
103 * specified. This is illegal, since the service would lack an identifier.
105 * @param aSD is the service description into which this hostlet may further
106 * define other service specific information, like facets. Note that this
107 * call back is "stronger" than Endpoint() and Contract(), and thus any
108 * value specified in this method will be in effect for the hostlet connection.
110 inline virtual void DescribeServiceL(CSenXmlServiceDescription& aSD)
112 aSD.SetEndPointL(Endpoint());
113 aSD.SetContractL(Contract());
114 aSD.SetFrameworkIdL(FrameworkId());
118 * This callback function is invoked each time when any hostlet connection's
119 * asynchronous RespondL is completed. Method can be used to trigger the
120 * release of some response releated system resources, as it is invoked
121 * after the response has been delivered to the consumer (application
122 * may wish to close handles to reserved file or memory).
124 * @param aTxnId identifies what transaction (service message) was completed
125 * @param aCompletionCode indicates whether transaction completed ok (KErrNone)
126 * or not (error code).
127 * @param aDesc may provide additional information about completed transaction,
128 * typically this description is provided, if an error has occured.
129 * It is optional for hostlet implementation to implement this method.
131 inline virtual void OnServiceCompleteL(TInt /* aTxnId */,
132 TInt /* aCompletionCode */,
133 const TDesC8& /* aDesc*/ ) { ; }
136 * Hostlet connection calls this method several times, passing a different
137 * UID per each call. If application wants to provide particular interface
138 * to hostlet connection (web services stack), it needs to return a pointer
139 * to such M-class as a return value of this method. For any interface, that
140 * application has not implemented, it is supposed to return NULL.
141 * @param aUID is the unique identifier of some interface
142 * @return value should be a valid (void) pointer to any interface implemented
143 * by the application. NULL signalizes that application does not provide interface
146 inline virtual TAny* GetInterfaceByUid( TUid /* aUID */ ) { return NULL; };
150 #endif // M_SEN_HOSTLET_H