// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
//

/**
 @file
 @publishedPartner
 @released
*/

#ifndef MMTPTYPE_H
#define MMTPTYPE_H

#include <e32std.h>

/**
Defines the generic MTP data type interface. All non-opaque MTP data comprises
either a single atomic value of a simple type, or a set of atomic simple type
values organised according to some dataset structure. Structured datasets may 
take one of the following general forms:
    
    1. Flat - a contiguous collection of values. 
    2. Complex - a contiguous array or string of values.
    3. Compound - a mixed sequence of simple, flat, and complex types.
    
Any time data is passed as a parameter to an MTP operation, response or event; 
or any time data is passed in the data phase of a fully described operation, 
that data must be of a type that implements the generic MTP data type 
interface.
@publishedPartner
@released 
*/
class MMTPType
    {
    
public:

    /**
    Initiates a data read sequence on the type by providing a const pointer 
    to the first in the sequence of data chunks that make up the type's data 
    stream. Subsequent chunks in the sequence can be sequentially retrieved 
    using NextReadChunk.
    @param aChunk The const pointer to be set to point to the start of the 
    first data chunk. This pointer's length is set to zero if no data chunk
    exists or a processing error occurs.
    @return KErrNone, if successful and the read sequence IS NOT complete, i.e.
    there are one or more additional data chunks available in the read 
    sequence.
    @return KMTPChunkSequenceCompletion, if successful and the read sequence 
    IS complete, i.e. there are no more additional data chunks available in 
    the read sequence.
    @return KErrNotFound, if no data chunk is found.
    @return One of the system wide error codes, if a general processing 
    error occurs.
    @see NextReadChunk.
    */
    virtual TInt FirstReadChunk(TPtrC8& aChunk) const = 0;

    /**
    Continues a data read sequence on the type by providing a const pointer 
    to the next in the sequence of data chunks that make up the type's data 
    stream. This data read sequence should have been previously initiated by 
    invoking FirstReadChunk.
    @param aChunk The const pointer to be set to point to the start of the 
    next data chunk. This pointer's length is set to zero if no data chunk
    exists or a processing error occurs.
    @return KErrNone, if successful and the read sequence IS NOT complete, i.e.
    there are one or more additional data chunks available in the read 
    sequence.
    @return KMTPChunkSequenceCompletion, if successful and the read sequence 
    IS complete, i.e. there are no more additional data chunks available in the 
    read sequence.
    @return KErrNotReady, if there is no data read sequence in progress, i.e.
    a read sequence was not previously initiated by invoking FirstReadChunk.
    @return One of the system wide error codes, if a general processing 
    error occurs.
    @see FirstReadChunk.
    */
    virtual TInt NextReadChunk(TPtrC8& aChunk) const = 0;

    /**
    Initiates a data write sequence on the type by providing a non-const 
    pointer to the first in the sequence of data chunks that make up the type's 
    data stream. Subsequent chunks in the sequence can be sequentially 
    retrieved using NextWriteChunk.
    @param aChunk The non-const pointer to be set to point to the start of the 
    first data chunk. If successful, the pointer's Length is set to zero, and 
    MaxLength is set to the available capacity of the data chunk. If not 
    successful, the pointer's MaxLength is set to zero.
    @return KErrNone, if successful and the write sequence IS NOT complete, 
    i.e. there are one or more additional data chunks available in the write 
    sequence.
    @return KMTPChunkSequenceCompletion, if successful and the write sequence 
    IS complete, i.e. there are no more additional data chunks available in the 
    write sequence.
    @return KErrNotFound, if no data chunk is found.
    @return One of the system wide error codes, if a general processing 
    error occurs.
    @see NextWriteChunk.
    */
    virtual TInt FirstWriteChunk(TPtr8& aChunk) = 0;

    /**
    Continues a data write sequence on the type by providing a non-const 
    pointer to the next in the sequence of data chunks that make up the type's 
    data stream. This data write sequence should have been previously initiated 
    by invoking FirstWriteChunk.
    @param aChunk The non-const pointer to be set to point to the start of the 
    next data chunk. If successful, the pointer's Length is set to zero, and 
    MaxLength is set to the available capacity of the data chunk. If not 
    successful, the pointer's MaxLength is set to zero..
    @return KErrNone, if successful and the write sequence IS NOT complete, i.e.
    there are one or more additional data chunks available in the write 
    sequence.
    @return KMTPChunkSequenceCompletion, if successful and the write sequence 
    IS complete, i.e. there are no more additional data chunks available in the 
    write sequence.
    @return KErrNotReady, if there is no data write sequence in progress, i.e.
    a write sequence was not previously initiated by invoking FirstWriteChunk.
    @return One of the system wide error codes, if a general processing 
    error occurs.
    @see FirstReadChunk.
    */
    virtual TInt NextWriteChunk(TPtr8& aChunk) = 0;
    
    /**
    Provides the size in bytes of the MTP data type.
    @return The types size in bytes.
    */
    virtual TUint64 Size() const = 0;
        
    /**
    Provides the MTP data type identification datacode.
    @return The MTP data type identification datacode.
    */
    virtual TUint Type() const = 0;
    
    /**
    Commits the specified write data chunk. This method should only be invoked 
    if the type indicates that committing data is required 
    (@see CommitRequired). Generally this would only be required by types which 
    are performing intermediate buffering, e.g. a file data object.
    @param aChunk The data chunk to be commited.
    @leave KErrNotSupported, if the type does not support data commit.
    @leave KMTPDataTypeInvalid, if the data type is structurally invalid.
    @leave One of the system wide error codes, if a general processing error 
    occurs.
    @see CommitRequired
    */
    IMPORT_C virtual MMTPType* CommitChunkL(TPtr8& aChunk);
    
    /**
    Indicates if the data type requires that data be committed during data
    write sequences. Generally this would only be required by types which 
    perform intermediate buffering (e.g. a file data object), or by data 
    types whose final structure is determined by the value of meta data 
    elements within the data stream itself (e.g an MTP ObjectPropDesc dataset).
    @return ETrue if CommitChunkL should be called after each invocation of 
    ChunkWritePtr, otherwise EFalse.
    @see CommitChunkL
    @see ChunkWritePtr
    */
    IMPORT_C virtual TBool CommitRequired() const;
    
    /**
    Validates the structural integrity of the data type. This method can be
    invoked on completion of a data write sequence to validate that the 
    received data represents a structurally valid instance of the data type.
    @return KErrNone if the data type is structurally valid, otherwise 
    KMTPDataTypeInvalid.
    */
    IMPORT_C virtual TInt Validate() const;

    /**
    Copies the data from one MTP data type object to another. This is 
    accomplished by attaching read and write data streams from the source 
    object to the sink object. The source and sink objects are not 
    required to be of the same type and no type compatibility checking is 
    performed.
    @param aFrom The MTP source data type object.
    @param aTo The MTP source data type object.
    @leave One of the system wide error codes, if a general processing error 
    occurs.
    */
	IMPORT_C static void CopyL(const MMTPType& aFrom, MMTPType& aTo);
    
    /**
    Provides an MTP data type extension interface implementation 
    for the specified interface Uid. 
    @param aInterfaceUid The unique identifier for the extension interface being 
    requested.
    @return Pointer to an interface instance or 0 if the interface is not 
    supported. Ownership is NOT transfered.
    */
    IMPORT_C virtual TAny* GetExtendedInterface(TUid aInterfaceUid);

    IMPORT_C virtual TInt FirstWriteChunk(TPtr8& aChunk, TUint aDataLength);
    
    IMPORT_C virtual TInt NextWriteChunk(TPtr8& aChunk, TUint aDataLength);
    
    IMPORT_C virtual TBool ReserveTransportHeader(TUint aHeaderLength, TPtr8& aHeader);
    };
    
/**
MTP completion code +17 : Indicates that a data type read or write data 
sequence has successfully completed. This code does not indicate an error 
condition.
@see FirstReadChunk.
@see NextReadChunk.
@see FirstWriteChunk.
@see NextWriteChunk.
*/
const TInt KMTPChunkSequenceCompletion = (+17);
    
/**
MTP completion code -20 : Indicates that a data type is structurally invalid.
@see CommitChunkL
@see Validate.
*/
const TInt KMTPDataTypeInvalid = (-20);
    
#endif // MMTPTYPE_H