Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: cchfdatasupplier.h
Link against: chf.lib

This item is not part of the S60 3rd Edition SDK for Symbian OS, Feature Pack 2.

Class CCHFDataSupplier

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 SetReadPosition(TUint32 aReadPositionInBytes, TUint32 aReadLengthInBytes) 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 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 RxReady() or ReceivedCompleteL()

Derivation

Members

Defined in CCHFDataSupplier:
BaseConstructL(), CCHFDataSupplier(), CCHFDataSupplier_Reserved_3(), CCHFDataSupplier_Reserved_4(), ContentType(), EContentTypeKnown, EContentTypeUnknown, File(), GetContentAccessIntent(), GetContentAccessIntent(), GetFile(), NewFromFileHandleL(), NewFromFileHandleL(), Observer(), Read(), RecognizeDataL(), RecognizeDataL(), Reset(), ResourceSize(), Resume(), RxReady(), SetContentAccessIntent(), SetContentTypeL(), SetObserver(), SetReadPosition(), SetReadPosition(), Start(), Suspend(), TContentTypeStatus, Uri(), iContentStatus, ~CCHFDataSupplier()

Inherited from CActive:
Cancel(), Deque(), DoCancel(), EPriorityHigh, EPriorityIdle, EPriorityLow, EPriorityStandard, EPriorityUserInput, Extension_(), IsActive(), IsAdded(), Priority(), RunError(), RunL(), SetActive(), SetPriority(), TPriority, iStatus

Inherited from CBase:
Delete(), operator new()

See also:


Construction and destruction


~CCHFDataSupplier()

IMPORT_C ~CCHFDataSupplier();

Description

Destructor.

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

See also:


CCHFDataSupplier()

protected: IMPORT_C CCHFDataSupplier(TInt aPriority);

Description

Constructor.

Parameters

TInt aPriority

Specifies the Active Object priority to be applied to this object

See also:

[Top]


Member functions


Start()

virtual TInt Start(MCHFDataSupplierObserver &aObserver)=0;

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

See also:


Read()

virtual TInt Read(TPtrC8 &aReadBuffer)=0;

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 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


RxReady()

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


SetReadPosition()

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


SetReadPosition()

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 aReadPositionInBytes, TUint32 aReadLengthInBytes)

Parameters

TUint32 aReadPositionInBytes

Contains the new read position in bytes

Return value

TInt

See CCHFDataSupplier::SetReadPosition(TUint32 aReadPositionInBytes, TUint32 aReadLengthInBytes)


SetObserver()

virtual IMPORT_C void SetObserver(MCHFDataSupplierObserver &aObserver);

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


Suspend()

virtual IMPORT_C 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.


Resume()

virtual IMPORT_C 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.


ContentType()

virtual IMPORT_C 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

TContentTypeStatus

EContentTypeKnown if content type is set, otherwise EContentTypeUnknown


SetContentTypeL()

virtual IMPORT_C 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


Uri()

virtual IMPORT_C const TDesC8 &Uri() const;

Description

Gets the URI of the resource.

Return value

const TDesC8 &

A const reference to the URI


File()

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


ResourceSize()

virtual IMPORT_C TUint32 ResourceSize() const;

Description

Gets the resource's total content size.

Return value

TUint32

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


Observer()

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


Reset()

virtual IMPORT_C TInt Reset();

Description

Called by the client to reinitialise the data connection.

Post-Condition

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

Return value

TInt

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


GetContentAccessIntent()

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


SetContentAccessIntent()

IMPORT_C TInt SetContentAccessIntent(ContentAccess::TIntent aContentAccessIntent);

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


NewFromFileHandleL()

static IMPORT_C CCHFDataSupplier *NewFromFileHandleL(RFile &aFile, TUint aBufferSizeInBytes);

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 *


NewFromFileHandleL()

static IMPORT_C 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 *


RecognizeDataL()

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 TDesC &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())


RecognizeDataL()

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())


BaseConstructL()

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


GetFile()

private: virtual IMPORT_C 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


GetContentAccessIntent()

private: virtual IMPORT_C void GetContentAccessIntent(ContentAccess::TIntent *&aContentAccessIntent);

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


CCHFDataSupplier_Reserved_3()

private: virtual IMPORT_C void CCHFDataSupplier_Reserved_3();

Description


CCHFDataSupplier_Reserved_4()

private: virtual IMPORT_C void CCHFDataSupplier_Reserved_4();

Description

[Top]


Member enumerations


Enum TContentTypeStatus

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.

[Top]


Member data


iContentStatus

protected: TContentTypeStatus iContentStatus;

Description

Holds the status of the content type buffer.

See also: