Factory +Implementation

The PDD factory creates the main media driver objects.

The Device Driver +Guide describes the general theory for implementing a derived class, +while this section gives the specifics for the media driver.

In implementing your DPhysicalDevice derived class, +you must, as a minimum, provide an implementation for the following four functions, +defined as pure virtual in DPhysicalDevice:

Install() - complete the initialisation of the PDD factory object
Create() - create the media driver object
Validate() - check that the PDD is suitable for use
GetCaps() - return the capabilities of the Media Driver

The following function is virtual in DPhysicalDevice but +has a default implementation that must be changed:

Info() - set the priority of the media driver

Install() - +complete the initialisation of the PDD factory object

See also DPhysicalDevice::Create().

This +PDD factory function is called by the device driver framework to create, and +return, the media driver object. This is an instance of a class derived from DMediaDriver. +Note that, occasionally, you may find this object referred to as the physical +channel.

Create() is called when initially mounting +a media device, or accessing a removable media after an insertion event. Contrast +this with Install(), +which is only called once, when the PDD factory object is loaded.

Typically, Create() does +the following:

Compares the build version +of the media driver with the version requested, and returns KErrNotSupported if +the versions are incompatible.
Creates an instance +of the DMediaDriver derived class, the media driver object.
Initiates second-phase +construction of the media driver object. Typically, this involves initialisation +that is capable of failing. This may be done synchronously or asynchronously. +You would probably do this asynchronously for removable media that is slow +to power up, or for slow internal media, in which case, you would need to +make sure that you attached a DFC queue during media +driver initialisation. Although the device driver framework does not +mandate any specific function name in which to implement this, the example +code fragment suggests a function name of DoCreate().
Acknowledges creation +of the media driver object. The way you do this depends on whether creation +is done synchronously or asynchronously:
- Synchronous creation +- call DMediaDriver::OpenMediaDriverComplete() passing KErrNone, +or an error code if appropriate, and then return KErrNone from Create(). +Do not return any value other than KErrNone from Create(), +otherwise the framework may call it again.
  
  Note that DMediaDriver::OpenMediaDriverComplete() can +be called from within the media driver class, if that is the way the driver +is designed, but Create() must still return KErrNone.
- Asynchronous creation +- return either KErrNone, if initiation of the operation +was successful, or an error code, if the operation failed immediately. However, +it is the responsibility of the media driver object to signal completion.

The following is a typical example:

TInt DMyPhysicalDeviceMedia::Create(DBase*& aChannel, TInt aMediaId, const TDesC8* aInfo ,const TVersion &aVer) + { + // Check the build version of the media driver + if (!Kern::QueryVersionSupported(iVersion,aVer)) + { + return KErrNotSupported; + } + + //Create my DMediaDriver derived object + DMyMediaDriver* pD=new DMyMediaDriver (aMediaId); + aChannel=pD; + + // Call my media driver’s second-stage constructor + Tint r = KErrNoMemory; + if(pD) + { + r = pD->DoCreate(aMediaId); + } + + // Synchronous Creation (don’t do this if Asynchronous)… + if(r == KErrNone) + { + pD->OpenMediaDriverComplete(KErrNone); + } + + return r; + } +

Validate() +- check that the PDD is suitable for use