1 // Copyright (c) 2006-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 "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @publishedPartner

    19  @released

    20 */

    21 

    22 #ifndef MMTPDATAPROVIDERFRAMEWORK_H

    23 #define MMTPDATAPROVIDERFRAMEWORK_H

    24 

    25 #include <e32cmn.h>

    26 #include <e32def.h>

    27 #include <mtp/mtpdataproviderconfig.hrh>

    28 #include <mtp/mtpdataproviderapitypes.h>

    29 

    30 class MMTPConnection;

    31 class MMTPDataProviderConfig;

    32 class MMTPFrameworkConfig;

    33 class MMTPObjectMgr;

    34 class MMTPReferenceMgr;

    35 class MMTPStorageMgr;

    36 class MMTPType;

    37 class TMTPTypeEvent;

    38 class TMTPTypeResponse;

    39 class TMTPTypeRequest;

    40 class RFs;

    41 class MMTPDataCodeGenerator;

    42 

    43 /**

    44 Defines the MTP data provider framework layer application programming

    45 interface.

    46 @publishedPartner

    47 @released

    48 */

    49 class MMTPDataProviderFramework

    50     {

    51 public:

    52 

    53     /**

    54     Provides the unique identifier of the calling data provider.

    55     @return The data provider identifier.

    56     */

    57     virtual TUint DataProviderId() const = 0;

    58 

    59     /**

    60     Provides the current MTP operational mode.

    61     @return The current MTP operational mode.

    62     */

    63     virtual TMTPOperationalMode Mode() const = 0;

    64 

    65     /**

    66     Initiates a data object receive sequence in the MTP data provider framework

    67     layer. This method should only be invoked when processing the ERequestPhase

    68     of an MTP transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL),

    69     and causes the MTP session transaction state to transition to the

    70     @see EDataIToRPhase. The data object receive sequence is completed when the 

    71     MTP data provider framework layer initiates the @see EResponsePhase of the 

    72     MTP transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL).

    73     @param aData The MTP data object sink buffer.

    74     @param aRequest The MTP request dataset of the active MTP transaction.

    75     @param aConnection The handle of the MTP connection on which the transaction

    76     is being processed.

    77     @see CMTPDataProviderPlugin::ProcessRequestPhaseL

    78     @leave KErrNotReady, if invoked when the current MTP transaction phase is

    79     not ERequestPhase.

    80     */

    81     virtual void ReceiveDataL(MMTPType& aData, const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

    82 

    83     /**

    84     Initiates a data object send sequence in the MTP data provider framework

    85     layer. This method should only be invoked when processing the ERequestPhase

    86     of an MTP transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL),

    87     and causes the MTP session transaction state to transition to the

    88     @see EDataRToIPhase. The data object send sequence is completed when the 

    89     MTP data provider framework layer initiates the @see EResponsePhase of the 

    90     MTP transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL).

    91     @param aData The MTP data object source buffer.

    92     @param aRequest The MTP request dataset of the active MTP transaction.

    93     @param aConnection The handle of the MTP connection on which the transaction

    94     is being processed.

    95     @see CMTPDataProviderPlugin::ProcessRequestPhaseL

    96     @leave KErrNotReady, if invoked when the current MTP transaction phase is

    97     not ERequestPhase.

    98     */

    99     virtual void SendDataL(const MMTPType& aData, const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

   100 

   101     /**

   102     Signals the MTP data provider framework layer to send an asynchronous event

   103     dataset on the specified MTP connection.

   104     @param aEvent The MTP event dataset source buffer.

   105     @param aConnection The handle of the MTP connection on which the event is

   106     to be sent.

   107     @leave KErrArgument, if the event data is not valid.

   108     */

   109     virtual void SendEventL(const TMTPTypeEvent& aEvent, MMTPConnection& aConnection) = 0;

   110 

   111     /**

   112     Signals the MTP data provider framework layer to send an asynchronous event

   113     dataset on all active MTP connections.

   114     @param aEvent The MTP event dataset source, this should always target all

   115     open sessions, i.e. SessionID should be set to KMTPAllSessions.

   116     @leave KErrArgument, if the event data is invalid.

   117     */

   118     virtual void SendEventL(const TMTPTypeEvent& aEvent) = 0;

   119 

   120     /**

   121     Initiates an MTP response dataset send sequence in the MTP data provider

   122     framework layer. This method should only be invoked when processing either

   123     the @see ERequestPhase or @see EResponsePhase of an MTP transaction, (@see

   124     CMTPDataProviderPlugin::ProcessRequestPhaseL) and causes the MTP session

   125     transaction state to transition to the @see ECompletingPhase. The MTP 

   126     response dataset send sequence is completed when the MTP data provider 

   127     framework layer initiates the @see ECompletingPhase of the MTP transaction 

   128     (@see CMTPDataProviderPlugin::ProcessRequestPhaseL).

   129     @param aResponse The MTP aResponse dataset source buffer.

   130     @param aConnection The handle of the MTP connection on which the transaction

   131     is being processed.

   132     @see CMTPDataProviderPlugin::ProcessRequestPhaseL

   133     @leave KErrNotReady, if invoked when the current MTP transaction phase is

   134     not ERequestPhase or EResponsePhase.

   135     */

   136     virtual void SendResponseL(const TMTPTypeResponse& aResponse, const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

   137 

   138     /**

   139     Signals to the MTP data provider framework layer that all processing

   140     related to the current transaction has been completed. This method should

   141     only be invoked when processing the @see ECompletingPhase of the MTP 

   142     transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL), and causes 

   143     the MTP session transaction state to transition to the @see EIdle state.

   144     @param aRequest The MTP request dataset that initiated the transaction.

   145     @param aRequest The MTP request dataset of the active MTP transaction.

   146     @param aConnection The handle of the MTP connection on which the transaction

   147     is being processed.

   148     @see CMTPDataProviderPlugin::ProcessRequestPhaseL

   149     @leave KErrNotReady If invoked when the current MTP transaction phase is

   150     invalid.

   151     */

   152     virtual void TransactionCompleteL(const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

   153 

   154     /**

   155     Registers the calling data provider to receive one or more occurrences of 

   156     the specified request dataset that are received on the specified 

   157     connection. This method should be used to register the calling data 

   158     provider to receive the following request types:

   159     

   160         1.  Follow-on requests of an MTP operation that can span multiple 

   161             transaction cycles. The following request types are recognised

   162             by the framework as follow-on requests:

   163             

   164             i)  SendObject (preceded by SendObjectInfo or SendObjectPropList). 

   165             ii) TerminateOpenCapture (preceded by InitiateOpenCapture).

   166             

   167         2.  MTP vendor extension requests.

   168         

   169     Note that:

   170 

   171         1.  The request dataset being registered must minimally specify the

   172             Operation Code of the expected operation and the SessionID on which 

   173             the operation request is expected to be received. 

   174             

   175             Follow-on request registrations MUST specify a specific SessionID. 

   176             Registrations of non follow-on requests may optionally specify a 

   177             SessionID of @see KMTPSessionAll to receive matching requests from

   178             any active MTP session.

   179            

   180         2.  With the exception of the TransactionID element, registered request

   181             datasets must exactly match all data elements of the expected request 

   182             dataset in order to be successfully routed.

   183            

   184         3.  Duplicate RouteRequestRegisterL registrations are not permitted. A request 

   185             dataset that matches that of a previous registration by this or 

   186             any other data provider on the same MTP session will result in the 

   187             previous registration being superceded.

   188            

   189         4.  Pending RouteRequestRegisterL registrations can be withdrawn at any time

   190             using the @see RouteRequestUnregisterL method. 

   191            

   192         5.  RouteRequestRegisterL registrations of MTP request types which ARE 

   193             recognised by the framework as MTP follow-on requests (SendObject, 

   194             TerminateOpenCapture) will result in at most one matching request 

   195             occurence being routed to the data provider. To receive another 

   196             request dataset of the same type, a new @see RouteRequestRegisterL 

   197             registration must be made.

   198             

   199         6   RouteRequestRegisterL registrations of MTP request types which ARE

   200             NOT recognised by the framework as MTP follow-on requests will 

   201             result in all matching requests which are subsequently received 

   202             being routed to the data provider. This will continue until such 

   203             time as the RouteRequestRegisterL registration is withdrawn using 

   204             the @see RouteRequestUnregisterL method.

   205             

   206         7.  RouteRequestRegisterL registrations request datasets which specify 

   207             an SessionID value of @see KMTPSessionAll, will result in matching 

   208             requests which are subsequently received on any active MTP session

   209             being routed to the data provider.

   210 

   211     @param aRequest The operation request dataset being registered.

   212     @param aConnection The handle of the MTP connection on which the operation

   213     request is expected to be received.

   214     @leave KErrArgument, if the request dataset does meet the minimal

   215     registration requirements specified above.

   216     @leave One of the system wide error codes, if a general processing error

   217     occurs.

   218     @see RouteRequestUnregisterL

   219     */

   220     virtual void RouteRequestRegisterL(const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

   221 

   222     /**

   223     Cancels a pending RouteRequestRegisterL registration.

   224     @param aRequest The registered operation request dataset.

   225     @param aConnection The handle of the MTP connection for which the operation

   226     request was registered.

   227     @leave One of the system wide error codes, if a general processing error

   228     occurs.

   229     @see RouteRequestRegisterL

   230     */

   231     virtual void RouteRequestUnregisterL(const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

   232 

   233     /**

   234     Signals the completion of the data provider's object store enumeration

   235     sequence that was previously initiated by a StartObjectEnumerationL signal

   236     made to the MTP data provider interface.

   237     @param aStorageId The MTP StorageID of the enumerated storage. This should 

   238     match the value specified in the preceding StartObjectEnumerationL.

   239     @see MMTPDataProvider::StartObjectEnumerationL

   240     */

   241     virtual void ObjectEnumerationCompleteL(TUint32 aStorageId) = 0;

   242 

   243     /**

   244     Signals the completion of the data provider's storage enumeration sequence

   245     that was previously initiated by a StartStorageEnumerationL signal

   246     made to the MTP data provider interface.

   247     @see MMTPDataProvider::StartStorageEnumerationL

   248     */

   249     virtual void StorageEnumerationCompleteL() = 0;

   250 

   251     /**

   252     Provides a handle to the configurability data specified in the data 

   253     provider's configuration file. 

   254     @return Handle to the data provider's configurability data.

   255     */

   256     virtual const MMTPDataProviderConfig& DataProviderConfig() const = 0;

   257 

   258     /**

   259     Provides a handle to the data provider framework configurability parameter 

   260     data. 

   261     @return Handle to the data provider framework configurability data.

   262     */

   263     virtual const MMTPFrameworkConfig& FrameworkConfig() const = 0;

   264 

   265     /**

   266     Provides a handle to the MTP object manager, which manages the assignment

   267     of MTP object handles and their mapping to actual data objects on behalf

   268     of the data provider.

   269     @return Handle to the MTP data provider framework object manager.

   270     */

   271     virtual MMTPObjectMgr& ObjectMgr() const = 0;

   272 

   273     /**

   274     Provides a handle to the MTP object reference manager, to which data

   275     providers can delegate the handling of the MTP persistent, abstract

   276     object referencing mechanism.

   277     @return Handle to the MTP data provider framework object reference manager.

   278     */

   279     virtual MMTPReferenceMgr& ReferenceMgr() const = 0;

   280 

   281     /**

   282     Provides a handle to the MTP storage manager, which manages the assignment 

   283     of MTP storage identifiers on behalf of the data provider.

   284     @return Handle to the MTP data provider framework storage manager.

   285     */

   286     virtual MMTPStorageMgr& StorageMgr() const = 0;

   287     

   288     /**

   289     Provides a handle to the MTP data provider framework RFs session.

   290     @return Handle to the MTP data provider framework RFs session.

   291     */

   292     virtual RFs& Fs() const = 0;

   293     

   294     /**

   295     Provides a handle to the MTP datacode generator, which generate the datacode of service properties , formats and methods etc.

   296     @return Handle to the MTP datacode generator.

   297     */

   298     virtual MMTPDataCodeGenerator& DataCodeGenerator() const = 0;

   299    

   300     };

   301 

   302 #endif // MMTPDATAPROVIDERFRAMEWORK_H