Class DLogicalDevice

DLogicalDevice

Support

Supported from 5.0

Description

The abstract base class for the LDD factory object.

This is also referred to as the logical device.

Derivation

CBase Base class for all classes to be instantiated on the heap CObject Implements reference counting to track concurrent references to itself DLogicalDevice The abstract base class for the LDD factory object

Defined in DLogicalDevice:
CreateL(), DLogicalDevice(), GetCaps(), Install(), IsAvailable(), Library(), QueryVersionSupported(), Remove(), iLibrary, iOpenChannels, iParseMask, iUnitsMask, iVersion, ~DLogicalDevice()

Inherited from CBase:
operator new()

Inherited from CObject:
AccessCount(), Close(), Dec(), FullName(), Inc(), Name(), Open(), Owner(), SetName(), SetNameL(), SetOwner(), UniqueID()

protected : DLogicalDevice();

Description

Default constructor.

The constructor is protected to prevent objects of this class from being constructed. This class is intended only as an abstract base for other classes.

Typically, a derived class provides a constructor that initialises the data members: iVersion, iParseMask and iUnitsMask.

See also:

• iVersion
• iParseMask
• iUnitsMask

protected : ~DLogicalDevice();

Description

Destructor.

This implementation is empty.

virtual TInt Install() = 0;

Description

Completes the installation of this logical device.

The function gives this logical device factory object the opportunity to do secondary initialization. It is called after the logical device has been successfully constructed on the Kernel heap as a result of a user side call to User::LoadLogicalDevice().

As a minimum, the function must define the name of the logical device; this is the way that the logical device is identified. For example:

_LIT(KName,"Myname");
return(SetName(&KName));

where CObject::SetName() is a member of the base class, and the format of any name obeys the standard rules.

Return value

TInt KErrNone, if successful; otherwise, one of the other system wide error codes.

See also:

• User::LoadLogicalDevice()
• CObject::SetName()

virtual void GetCaps(TDes8& aDes) const = 0;

Description

Gets the capabilities of this logical device.

The function is called by the Kernel as a result of a user side request to the GetCaps() member function of the corresponding RDevice handle.

Symbian OS does not define how a device's capabilities are encoded. Any encoding scheme must follow a convention that is understood by the user side caller of RDevice::GetCaps().

A common convention is simply to return the version of the LDD on the grounds that capabilities correlate with the version.

The following is a typical implementation that returns the version number. The class DMyDerived is derived from DLogicalDevice.

class TCapsTest
          {
    public :
          TVersion version;
          };

    DMyDerived::GetCaps(TDes8& aDes)
          {
          TCapsTest caps;
          caps,version = iVersion;
          aDes.FillZ(aDes.MaxLength());
          aDes.Copy((TUint8*)&caps,Min(aDes.MaxLength(),sizeof(caps)));
          }

Parameters

TDes8& aDes On return, contains information describing the capabilities of the device.

See also:

• RDevice::GetCaps()

virtual DLogicalChannel* CreateL() = 0;

Description

Creates a logical channel.

The function is called by the Kernel as a result of a request to construct a logical channel. The request is initiated from the user side by a call to RBusLogicalChannel::DoCreate(). This in turn is called by an 'open' type member function of a class derived from RBusLogicalChannel supplied by the developer of the LDD.

A typical implementation is:

{
    DLogicalChannel* pC = new(ELeave) DDerivedLChan(this);
    return pC;
    }

where DDerivedLChan is some class derived from DLogicalChannel.

Return value

DLogicalChannel* A pointer to a Kernel side logical channel object, an instance of a DLogicalChannel derived class.

See also:

• RBusLogicalChannel::DoCreate()

virtual TInt Remove();

Description

Performs final processing before removing this logical device.

This function is called by the Kernel as a result of a call to User::FreeLogicalDevice(). It is called before:

• Close() is called on this object

• Close() is called on the LDD library.

The function is also called by the Kernel if a call to User::LoadLogicalDevice() fails. Specifically, the function is called if the attempt to add this DLogicalDevice object to the Kernel's list of logical devices fails. In this event, Remove() is called before Close() is called on this object.

The function gives the logical device the opportunity to do any further final processing before it is closed; it should return KErrNone.

The default implementation just returns KErrNone.

Return value

TInt KErrNone.

Notes:

• This DLogicalDevice object is destroyed and the LDD library is unloaded when their respective reference counts reach zero.

See also:

• User::FreeLogicalDevice()
• User::LoadLogicalDevice()
• CObject::Close()

virtual TBool QueryVersionSupported(const TVersion& aVer) const;

Description

Tests whether the specified version is supported by this logical device.

The function is called by the Kernel as a result of a user side call to RDevice::QueryVersionSupported().

An implementation supplied by a derived class should decide whether the specified version is supported by this logical device and return true or false.

The default implementation returns the result of a call to User::QueryVersionSupported() taking the version with which this DLogicalDevice object is built as the reference version and the specified version as the test version; i.e. the default implementation returns true if one of the following two conditions is true and returns false if neither are true:

• the aVer major number < this DLogicalDevice major number

• the aVer major number == this DLogicalDevice major number && the aVer minor number <= this DLogicalDevice minor number.

Parameters

const TVersion& aVer The version to be compared against the version with which this DLogicalDevice is built

Return value

TBool True, if the specified version is supported by this logical device; false, otherwise.

See also:

• RDevice::QueryVersionSupported()
• User::QueryVersionSupported()
• TVersion

virtual TBool IsAvailable(TInt aUnit,const TDesC* aDriver,const TDesC* anInfo) const;

Description

Tests whether a unit is supported.

The function is called by the Kernel as a result of a user side Call to RDevice::IsAvailable().

An implementation supplied by a derived class should decide whether the specified unit and the additional information specified by the const TDesC* anInfo argument coupled with the name of the PDD specified by the const TDesC* aDriver argument, is supported, and return true if it is or false if not.

The default implementation always returns true.

Parameters

TInt aUnit The unit. const TDesC* aDriver A pointer to a descriptor containing the name of the PDD; this pointer can be NULL. const TDesC* anInfo A pointer to a descriptor containing additional information; this pointer can be NULL.

Return value

TBool True, if the unit is supported; false, otherwise.

Notes:

• The device driver framework does not define the meaning of a unit. Any implementation depends on the nature of the device.

DLibrary* Library();

Description

Gets a pointer to the LDD library.

Return value

DLibrary* A pointer to the LDD library.

protected : TVersion iVersion;

Description

The version of this logical device.

This is used to check that an LDD and PDD are compatible. Typically, this is set by the constructor of a derived class.

protected : TUint iParseMask;

Description

A bitmask that indicates device properties.

This can take the following values:

• KDeviceAllowUnit

• KDeviceAllowPhysicalDevice

• KDeviceAllowInfo

• KDeviceAllowAll

Typically, this is set by the constructor of a derived class.

See also:

• RBusLogicalChannel::DoCreate()

protected : TUint iUnitsMask;

Description

Indicates which units are valid.

If units are allowed, i.e. iParseMask&KDeviceAllowMask returns true, then this mask indicates which of the units (from 0 to 31) are valid.

The DPhysicalDevice object associated with the PDD has a similar mask, and both masks are used to indicate which units the LDD-PDD pair can handle.

Typically, this is set by the constructor of a derived class.

See also:

• DPhysicalDevice

private : DLibrary *iLibrary;

Description

This is internal and is not intended for use.

private : TInt iOpenChannels;

Description

This is internal and is not intended for use.