CCHFDataSupplier in Content Handling Content_Handling

class CCHFDataSupplier : public CActive;

Description

Base class for all Content Handling Framework Data Suppliers.

Data Suppliers provides the content of a URI-identified resource to a client.

The class is derived from CActive to provide derived classes the mechanism for using their component in asynchronous transactions if required. Derived CCHFDataSupplier class designers and users take full responsibility for managing the addition of their component to an active scheduler. Most data suppliers will exhibit asynchronous behaviour and the API is designed to reflect this.

After creation of a data supplier component, the user of the component follows this recommended order of operation;

1. User optionally calls CCHFDataSupplier::SetReadPosition(TUint32,TUint32) to specify range

2. User calls Start(..) on the component to supplier an observer interface and to commence reading

3. Data Supplier calls ReceivedCompleteL() on the observer to indicate availability of content

4. User calls ContentType(..) to retrieve the content type.

5. User calls Read(..) to retrieve the content

6. User calls CCHFDataSupplier::RxReady() to indicate readiness to receive more data

7. Data Supplier calls ReceivedCompleteL() on the observer to indicate availability of more data

8. Steps 5 to 6 is repeated until KErrEof is reported by either CCHFDataSupplier::RxReady() or ReceivedCompleteL()

Derivation

CBase - Base class for all classes to be instantiated on the heap.

CActive - The core class of the active object abstraction.

CCHFDataSupplier - Base class for all Content Handling Framework Data Suppliers.

Members

Defined in CCHFDataSupplier:

BaseConstructL(const TDesC8 &)Initialises the Data Supplier base class. Call this method in your derived class...
CCHFDataSupplier(TInt)Constructor.
CCHFDataSupplier_Reserved_3()
CCHFDataSupplier_Reserved_4()
ContentType(TPtrC8 &)constGets the content type of the resource.
EContentTypeKnownContent type is known.
EContentTypeUnknownContent type is unknown.
File()The public calling API for getting the file-handle of the resource, if the conte...
GetFile(RFile *&)The private virtual function for getting the file-handle of the resource, if the...
NewFromFileHandleL(RFile &,TUint)Creates a CCHFDataSupplier object given a file-handle (rather than a URI).
Observer()constGets the data supplier's observer.
Read(TPtrC8 &)Reads the portion of data received.
RecognizeDataL(RFile &)Attempts recognition of the content MIME type.
RecognizeDataL(const TDesC &,const TDesC8 &)Attempts recognition of the content MIME type.
Reset()Called by the client to reinitialise the data connection.
ResourceSize()constGets the resource's total content size.
Resume()Resumes the Data Supplier from a suspended state.
RxReady()Called by the client to indicate readiness to receive more data.
SetContentTypeL(const TDesC8 &)Sets the content type to a client-specified value.
SetObserver(MCHFDataSupplierObserver &)Replaces the current Data Supplier Observer.
SetReadPosition(TUint32)Sets the data supplier read position.
SetReadPosition(TUint32,TUint32)Sets the range of data to be read.
Start(MCHFDataSupplierObserver &)Starts the Data Supplier call to supply an observer interface and to request the...
Suspend()Suspends activity on the Data Supplier.
TContentTypeStatusDescribes the status of the content type buffer; whether known, i.e. set, or not...
Uri()constGets the URI of the resource.
iContentStatusHolds the status of the content type buffer.
~CCHFDataSupplier()Destructor.

Inherited from CActive:

CActive(TInt)Constructs the active object with the specified priority.
Cancel()Cancels the wait for completion of an outstanding request.
Deque()Removes the active object from the active scheduler's list of active objects.
DoCancel()Implements cancellation of an outstanding request.
EPriorityHighA priority higher than EPriorityUserInput.
EPriorityIdleA low priority, useful for active objects representing background processing.
EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.
EPriorityStandardMost active objects will have this priority.
EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...
Extension_(TUint,TAny *&,TAny *)Extension function
IsActive()constDetermines whether the active object has a request outstanding.
IsAdded()constDetermines whether the active object has been added to the active scheduler's li...
Priority()constGets the priority of the active object.
RunError(TInt)Handles a leave occurring in the request completion event handler CActive::RunL(...
RunL()Handles an active object's request completion event.
SetActive()Indicates that the active object has issued a request and that it is now outstan...
SetPriority(TInt)Sets the priority of the active object.
TPriorityDefines standard priorities for active objects.
iStatusThe request status associated with an asynchronous request.

Inherited from CBase:

Delete(CBase *)Deletes the specified object.
operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TAny *)Initialises the object to binary zeroes.
operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

IMPORT_C ~CCHFDataSupplier();

Description

Destructor.

This delete the resources allocated in this base class and cancels the Active Object.

protected: IMPORT_C CCHFDataSupplier(TInt aPriority);

Description

Constructor.

Parameters


                                 						TInt aPriority

Specifies the Active Object priority to be applied to this object

Description

Starts the Data Supplier call to supply an observer interface and to request the Data Supplier to start supplying data.

Parameters


                                 						MCHFDataSupplierObserver &aObserver

Holds the reference to the data supplier observer

Return value

TInt

KErrNone if the process completes, otherwise some other error code

Pre-Condition

Clients should only call this method when they have been notified of a successful receive using the ReceivedCompleteL() method on the observer interface.

Description

Reads the portion of data received.

The data is not destroyed when the call returns and may be read repeatedly before the next call to CCHFDataSupplier::RxReady().

Parameters


                                 						TPtrC8 &aReadBuffer

Holds a reference to the descriptor that refers to the received data. Copying is avoided for speed.

Return value

TInt

KErrNone if the read is successful, otherwise some other error code

virtual TInt RxReady()=0;

Description

Called by the client to indicate readiness to receive more data.

Post-Condition

The last data is destroyed

Return value

TInt

KErrNone if the range was successfully set, otherwise some other error code, such as KErrEof

virtual TInt SetReadPosition(TUint32 aReadPositionInBytes, TUint32 aReadLengthInBytes)=0;

Description

Sets the range of data to be read.

Parameters

`TUint32 aReadPositionInBytes`	Specifies the position to move the read data pointer to, in bytes
`TUint32 aReadLengthInBytes`	Specifies the amount of data to read, in bytes. To read to the end of the resource set aReadLengthInBytes to KContentSizeUnknown.

Return value

TInt

KErrNone if successfully set, otherwise some other error code

IMPORT_C TInt SetReadPosition(TUint32 aReadPositionInBytes);

Description

Sets the data supplier read position.

Use this method to navigate the resource content by moving the read position. To set the range, instead of just the position, see CCHFDataSupplier::SetReadPosition(TUint32,TUint32)

Parameters


                                 						TUint32 aReadPositionInBytes

Contains the new read position in bytes

Return value

TInt

See CCHFDataSupplier::SetReadPosition(TUint32,TUint32)

Description

Replaces the current Data Supplier Observer.

Call this method to replace the observer of the Data Supplier. The new observer becomes the target of all subsequent call backs.

Parameters


                                 						MCHFDataSupplierObserver &aObserver

The new data supplier observer

IMPORT_C virtual TInt Suspend();

Description

Suspends activity on the Data Supplier.

Return value

TInt

KErrNone if successful, otherwise some other error code, such as KErrNotSupported. The base implementation returns KErrNotSupported.

IMPORT_C virtual TInt Resume();

Description

Resumes the Data Supplier from a suspended state.

Return value

TInt

KErrNone if successful, otherwise some other error code, such as KErrNotSupported. The base implementation returns KErrNotSupported.

IMPORT_C virtual TContentTypeStatus ContentType(TPtrC8 &aContentType) const;

Description

Gets the content type of the resource.

Parameters


                                 						TPtrC8 &aContentType

A descriptor that on return holds the content type, if the status of the content type is EContentTypeKnown. Check the return type before using.

Return value

CCHFDataSupplier::TContentTypeStatus

EContentTypeKnown if content type is set, otherwise EContentTypeUnknown

IMPORT_C virtual void SetContentTypeL(const TDesC8 &aNewContentType);

Description

Sets the content type to a client-specified value.

Call this method to override the content type of the resource for subsequent use by a content handler.

Parameters

const TDesC8 &aNewContentType

A descriptor containing the new content type

Leave codes

KErrNoMemory

IMPORT_C virtual const TDesC8& Uri() const;

Description

Gets the URI of the resource.

Return value

const TDesC8 &

A const reference to the URI

IMPORT_C RFile* File();

Description

The public calling API for getting the file-handle of the resource, if the content is being supplied by file-handle rather than by URI.

Return value

RFile *

A pointer to the file object, or NULL if the content is supplied by URI rather than by file-handle

Description

Gets the resource's total content size.

Return value

TUint32

Size of the resource in bytes. The base implementation returns KContentSizeUnknown.

IMPORT_C MCHFDataSupplierObserver& Observer() const;

Description

Gets the data supplier's observer.

Return value

MCHFDataSupplierObserver &

A reference to the current observer

Panic codes

CHFPanic::ECHFDataSupplierObserverNULL

Data Supplier Observer not set

IMPORT_C virtual TInt Reset();

Description

Called by the client to reinitialise the data connection.

Post-Condition

The data supplier is in its initial state. CCHFDataSupplier::Start(MCHFDataSupplierObserver &) must be called again to reuse the resource.

Return value

TInt

KErrNone if successful, otherwise some other error code, such as KErrNotSupported

IMPORT_C TInt GetContentAccessIntent(ContentAccess::TIntent &aContentAccessIntent) const;

Description

The public calling API for getting the content-access intent.

Parameters


                                 						ContentAccess::TIntent &aContentAccessIntent

The output content-access intent

Return value

TInt

KErrNone if successful, otherwise some other error code, such as KErrNotSupported

Description

The public calling API for setting the content-access intent.

Parameters


                                 						ContentAccess::TIntent aContentAccessIntent

The input content-access intent

Return value

TInt

KErrNone if successful, otherwise some other error code, such as KErrNotSupported

Description

Creates a CCHFDataSupplier object given a file-handle (rather than a URI).

Parameters

`RFile &aFile`	The file passed by handle
`TUint aBufferSizeInBytes`	The size of the buffer that the data supplier should use when retrieving data

Return value

CCHFDataSupplier *

IMPORT_C static CCHFDataSupplier* NewFromFileHandleL(RFile &aFile, TUint aBufferSizeInBytes, ContentAccess::TIntent aContentAccessIntent);

Description

Creates a CCHFDataSupplier object given a file-handle (rather than a URI).

Parameters

`RFile &aFile`	The file passed by handle
`TUint aBufferSizeInBytes`	The size of the buffer that the data supplier should use when retrieving data
`ContentAccess::TIntent aContentAccessIntent`	The CAF intent indicator

Return value

CCHFDataSupplier *

protected: IMPORT_C void RecognizeDataL(const TDesC &aFileName, const TDesC8 &aDataBuffer);

Description

Attempts recognition of the content MIME type.

This attempts to recognise the content MIME type given a portion of the content and its filename. It defaults the value of the content type to 'application/octet-stream' if there is no possible recognition, otherwise the content-type is set to the best guess of the content-type.

Post-Condition

Sets the content type status indicator, iContentStatus, to EContentTypeKnown

Parameters

`const TDesC16 &aFileName`	Descriptor containing the full filename, including drive and path
`const TDesC8 &aDataBuffer`	A descriptor containing a portion of the file, typically the start of the information.

Leave codes

`User::LeaveIfError(RApaLsSession::Connect())`
`User::LeaveIfError(RApaLsSession::RecognizeData())`

protected: IMPORT_C void RecognizeDataL(RFile &aFile);

Description

Attempts recognition of the content MIME type.

This attempts to recognise the content MIME type given a file-handle. It defaults the value of the content type to 'application/octet-stream' if there is no possible recognition, otherwise the content-type is set to the best guess of the content-type.

Post-Condition

Sets the content type status indicator, iContentStatus, to EContentTypeKnown

Parameters


                                 						RFile &aFile

The file to recognize

Leave codes

`User::LeaveIfError(RApaLsSession::Connect())`
`User::LeaveIfError(RApaLsSession::RecognizeData())`

protected: IMPORT_C void BaseConstructL(const TDesC8 &aUri);

Description

Initialises the Data Supplier base class. Call this method in your derived class' ConstructL() to set the URI of the data supplier.

Parameters

const TDesC8 &aUri

Leave codes

KErrNoMemory

private: IMPORT_C virtual void GetFile(RFile *&aFile);

Description

The private virtual function for getting the file-handle of the resource, if the content is being supplied by file-handle rather than by URI.

Parameters


                                 						RFile *&aFile

On return this points to the file object, or to NULL if the content is supplied by URI rather than by file-handle

Description

The private virtual function for getting the content-access intent value by non-const pointer, so that it can be read and modified.

Parameters


                                 						ContentAccess::TIntent *&aContentAccessIntent

On return this points to the intent value, or to NULL if this is not supported

private: IMPORT_C virtual void CCHFDataSupplier_Reserved_3();

Description

private: IMPORT_C virtual void CCHFDataSupplier_Reserved_4();

Description

TContentTypeStatus

Description

Describes the status of the content type buffer; whether known, i.e. set, or not.

`EContentTypeUnknown`	Content type is unknown.
`EContentTypeKnown`	Content type is known.

protected: TContentTypeStatus iContentStatus;

Description

Holds the status of the content type buffer.

Class CCHFDataSupplier

Description

Derivation

Members

Construction and destruction