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 MMTPTYPE_H

    23 #define MMTPTYPE_H

    24 

    25 #include <e32std.h>

    26 

    27 /**

    28 Defines the generic MTP data type interface. All non-opaque MTP data comprises

    29 either a single atomic value of a simple type, or a set of atomic simple type

    30 values organised according to some dataset structure. Structured datasets may 

    31 take one of the following general forms:

    32     

    33     1. Flat - a contiguous collection of values. 

    34     2. Complex - a contiguous array or string of values.

    35     3. Compound - a mixed sequence of simple, flat, and complex types.

    36     

    37 Any time data is passed as a parameter to an MTP operation, response or event; 

    38 or any time data is passed in the data phase of a fully described operation, 

    39 that data must be of a type that implements the generic MTP data type 

    40 interface.

    41 @publishedPartner

    42 @released 

    43 */

    44 class MMTPType

    45     {

    46     

    47 public:

    48 

    49     /**

    50     Initiates a data read sequence on the type by providing a const pointer 

    51     to the first in the sequence of data chunks that make up the type's data 

    52     stream. Subsequent chunks in the sequence can be sequentially retrieved 

    53     using NextReadChunk.

    54     @param aChunk The const pointer to be set to point to the start of the 

    55     first data chunk. This pointer's length is set to zero if no data chunk

    56     exists or a processing error occurs.

    57     @return KErrNone, if successful and the read sequence IS NOT complete, i.e.

    58     there are one or more additional data chunks available in the read 

    59     sequence.

    60     @return KMTPChunkSequenceCompletion, if successful and the read sequence 

    61     IS complete, i.e. there are no more additional data chunks available in 

    62     the read sequence.

    63     @return KErrNotFound, if no data chunk is found.

    64     @return One of the system wide error codes, if a general processing 

    65     error occurs.

    66     @see NextReadChunk.

    67     */

    68     virtual TInt FirstReadChunk(TPtrC8& aChunk) const = 0;

    69 

    70     /**

    71     Continues a data read sequence on the type by providing a const pointer 

    72     to the next in the sequence of data chunks that make up the type's data 

    73     stream. This data read sequence should have been previously initiated by 

    74     invoking FirstReadChunk.

    75     @param aChunk The const pointer to be set to point to the start of the 

    76     next data chunk. This pointer's length is set to zero if no data chunk

    77     exists or a processing error occurs.

    78     @return KErrNone, if successful and the read sequence IS NOT complete, i.e.

    79     there are one or more additional data chunks available in the read 

    80     sequence.

    81     @return KMTPChunkSequenceCompletion, if successful and the read sequence 

    82     IS complete, i.e. there are no more additional data chunks available in the 

    83     read sequence.

    84     @return KErrNotReady, if there is no data read sequence in progress, i.e.

    85     a read sequence was not previously initiated by invoking FirstReadChunk.

    86     @return One of the system wide error codes, if a general processing 

    87     error occurs.

    88     @see FirstReadChunk.

    89     */

    90     virtual TInt NextReadChunk(TPtrC8& aChunk) const = 0;

    91 

    92     /**

    93     Initiates a data write sequence on the type by providing a non-const 

    94     pointer to the first in the sequence of data chunks that make up the type's 

    95     data stream. Subsequent chunks in the sequence can be sequentially 

    96     retrieved using NextWriteChunk.

    97     @param aChunk The non-const pointer to be set to point to the start of the 

    98     first data chunk. If successful, the pointer's Length is set to zero, and 

    99     MaxLength is set to the available capacity of the data chunk. If not 

   100     successful, the pointer's MaxLength is set to zero.

   101     @return KErrNone, if successful and the write sequence IS NOT complete, 

   102     i.e. there are one or more additional data chunks available in the write 

   103     sequence.

   104     @return KMTPChunkSequenceCompletion, if successful and the write sequence 

   105     IS complete, i.e. there are no more additional data chunks available in the 

   106     write sequence.

   107     @return KErrNotFound, if no data chunk is found.

   108     @return One of the system wide error codes, if a general processing 

   109     error occurs.

   110     @see NextWriteChunk.

   111     */

   112     virtual TInt FirstWriteChunk(TPtr8& aChunk) = 0;

   113 

   114     /**

   115     Continues a data write sequence on the type by providing a non-const 

   116     pointer to the next in the sequence of data chunks that make up the type's 

   117     data stream. This data write sequence should have been previously initiated 

   118     by invoking FirstWriteChunk.

   119     @param aChunk The non-const pointer to be set to point to the start of the 

   120     next data chunk. If successful, the pointer's Length is set to zero, and 

   121     MaxLength is set to the available capacity of the data chunk. If not 

   122     successful, the pointer's MaxLength is set to zero..

   123     @return KErrNone, if successful and the write sequence IS NOT complete, i.e.

   124     there are one or more additional data chunks available in the write 

   125     sequence.

   126     @return KMTPChunkSequenceCompletion, if successful and the write sequence 

   127     IS complete, i.e. there are no more additional data chunks available in the 

   128     write sequence.

   129     @return KErrNotReady, if there is no data write sequence in progress, i.e.

   130     a write sequence was not previously initiated by invoking FirstWriteChunk.

   131     @return One of the system wide error codes, if a general processing 

   132     error occurs.

   133     @see FirstReadChunk.

   134     */

   135     virtual TInt NextWriteChunk(TPtr8& aChunk) = 0;

   136     

   137     /**

   138     Provides the size in bytes of the MTP data type.

   139     @return The types size in bytes.

   140     */

   141     virtual TUint64 Size() const = 0;

   142         

   143     /**

   144     Provides the MTP data type identification datacode.

   145     @return The MTP data type identification datacode.

   146     */

   147     virtual TUint Type() const = 0;

   148     

   149     /**

   150     Commits the specified write data chunk. This method should only be invoked 

   151     if the type indicates that committing data is required 

   152     (@see CommitRequired). Generally this would only be required by types which 

   153     are performing intermediate buffering, e.g. a file data object.

   154     @param aChunk The data chunk to be commited.

   155     @leave KErrNotSupported, if the type does not support data commit.

   156     @leave KMTPDataTypeInvalid, if the data type is structurally invalid.

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

   158     occurs.

   159     @see CommitRequired

   160     */

   161     IMPORT_C virtual MMTPType* CommitChunkL(TPtr8& aChunk);

   162     

   163     /**

   164     Indicates if the data type requires that data be committed during data

   165     write sequences. Generally this would only be required by types which 

   166     perform intermediate buffering (e.g. a file data object), or by data 

   167     types whose final structure is determined by the value of meta data 

   168     elements within the data stream itself (e.g an MTP ObjectPropDesc dataset).

   169     @return ETrue if CommitChunkL should be called after each invocation of 

   170     ChunkWritePtr, otherwise EFalse.

   171     @see CommitChunkL

   172     @see ChunkWritePtr

   173     */

   174     IMPORT_C virtual TBool CommitRequired() const;

   175     

   176     /**

   177     Validates the structural integrity of the data type. This method can be

   178     invoked on completion of a data write sequence to validate that the 

   179     received data represents a structurally valid instance of the data type.

   180     @return KErrNone if the data type is structurally valid, otherwise 

   181     KMTPDataTypeInvalid.

   182     */

   183     IMPORT_C virtual TInt Validate() const;

   184 

   185     /**

   186     Copies the data from one MTP data type object to another. This is 

   187     accomplished by attaching read and write data streams from the source 

   188     object to the sink object. The source and sink objects are not 

   189     required to be of the same type and no type compatibility checking is 

   190     performed.

   191     @param aFrom The MTP source data type object.

   192     @param aTo The MTP source data type object.

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

   194     occurs.

   195     */

   196 	IMPORT_C static void CopyL(const MMTPType& aFrom, MMTPType& aTo);

   197     

   198     /**

   199     Provides an MTP data type extension interface implementation 

   200     for the specified interface Uid. 

   201     @param aInterfaceUid The unique identifier for the extension interface being 

   202     requested.

   203     @return Pointer to an interface instance or 0 if the interface is not 

   204     supported. Ownership is NOT transfered.

   205     */

   206     IMPORT_C virtual TAny* GetExtendedInterface(TUid aInterfaceUid);

   207 

   208     IMPORT_C virtual TInt FirstWriteChunk(TPtr8& aChunk, TUint aDataLength);

   209     

   210     IMPORT_C virtual TInt NextWriteChunk(TPtr8& aChunk, TUint aDataLength);

   211     

   212     IMPORT_C virtual TBool ReserveTransportHeader(TUint aHeaderLength, TPtr8& aHeader);

   213     };

   214     

   215 /**

   216 MTP completion code +17 : Indicates that a data type read or write data 

   217 sequence has successfully completed. This code does not indicate an error 

   218 condition.

   219 @see FirstReadChunk.

   220 @see NextReadChunk.

   221 @see FirstWriteChunk.

   222 @see NextWriteChunk.

   223 */

   224 const TInt KMTPChunkSequenceCompletion = (+17);

   225     

   226 /**

   227 MTP completion code -20 : Indicates that a data type is structurally invalid.

   228 @see CommitChunkL

   229 @see Validate.

   230 */

   231 const TInt KMTPDataTypeInvalid = (-20);

   232     

   233 #endif // MMTPTYPE_H

   234