diff -r 000000000000 -r d0791faffa3f mtpfws/mtpfw/datatypes/interface/mmtptype.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mtpfws/mtpfw/datatypes/interface/mmtptype.h Tue Feb 02 01:11:40 2010 +0200 @@ -0,0 +1,234 @@ +// 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 + +/** +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 +