CDeviceTypeInformation Class Reference

#include <bafl/sysutil.h>

Link against: sysutil.lib

class CDeviceTypeInformation : public CBase

Inherits from

CDeviceTypeInformation

Nested Classes and Structures

CDeviceTypeInformation::TImpl

Public Attributes
const TInt	KDefaultValue
const TInt	KMaxAttributeLength

Public Member Functions
	~CDeviceTypeInformation()
IMPORT_C TInt	GetAttribute(const TUid &, TPtrC16 &)
IMPORT_C TInt	GetDefaultDeviceName(TPtrC16 &)
IMPORT_C TInt	GetManufacturerName(TPtrC16 &)
IMPORT_C TInt	GetModelCode(TPtrC16 &)
IMPORT_C TInt	GetModelName(TPtrC16 &)
IMPORT_C TInt	GetOSVersion(TPtrC16 &)
IMPORT_C TInt	GetOSVersion(TUint16 &, TUint16 &)
IMPORT_C TInt	GetRevisionID(TPtrC16 &)
IMPORT_C TInt	GetUIPlatformName(TPtrC16 &)
IMPORT_C TInt	GetUIPlatformVersion(TPtrC16 &)
IMPORT_C TInt	GetUIPlatformVersion(TUint16 &, TUint16 &)
CDeviceTypeInformation *	NewL()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

This class is used to hold the device type information attributes and provides member functions to return the attribute values. These values are strings of UTF-16 characters and no format must be assumed or implied as it varies from one device manufacturer to the next. Please note that this information does not identify a unique device but identifies the type of device.

An instance of this class cannot be created by user code. If device type information attributes are required then the user should use SysUtil::GetDeviceTypeInfoL which will return a pointer to an instance of this class. This instance will contain a full set of device type information attributes that have been provisioned by the device creator. For details of how these are provisioned see 'XXX xxx' document in the OS Developer Library.

For standard device type information attributes (attributes which are common to all device creators) named functions have been provided. These functions also offer the advantage of a default value being provided when an attribute has not been provisioned by the device creator. If a default value has been retrieved KDefaultValue will be returned.

Callers who do not care about whether a default value is retrieved or not can use the API as follows:

	TPtrC16 modelNamePtrC;
	User::LeaveIfError( deviceTypeInfo->GetModelName(modelNamePtrC) );

Where callers wish to avoid the default value it can be tested for as follows:

	TPtrC16 modelNamePtrC;
	if (User::LeaveIfError( deviceTypeInfo->GetModelName(modelNamePtrC)) == CDeviceTypeInformation::KDefaultValue)
		{
		// We have a default attribute value, do something else
		...
		}
	else
		{
		// We have a device creator supplied attribute value.
		...
		}

In addition to named functions, two additional generic functions are provided that can be used to retrieve any additional device type information attributes which may be provided by a device creator. These functions can also be used to retrieve the standard attributes; however, it is recommended that the named functions be used instead.

Any code which owns an instance of this class has the responsibility of destroying it. This may be achieved by calling delete on the pointer or using the CleanupStack.

Member Attribute Documentation

KDefaultValue

const TInt

KDefaultValue

[static]

This const is a value returned from calls to the named CDeviceTypeInformation APIs. It indicates to the caller that the returned device type information attribute, stored in CDeviceTypeInformation, is a default value. This occurs when the device creator does not provision the attribute value.

KMaxAttributeLength

const TInt

KMaxAttributeLength

[static]

The maximum length of a device attribute string value.

Constructor & Destructor Documentation

~CDeviceTypeInformation ( )

IMPORT_C

~CDeviceTypeInformation

(

)

Class destructor.

Performs any clean up such as deleting memory on the heap.

Member Function Documentation

GetAttribute ( const TUid &, TPtrC16 & )

IMPORT_C TInt	GetAttribute	(	const TUid &	aAttributeUid,
			TPtrC16 &	aValue
		)	const

Retrieves a reference to the attribute string which matches the provided UID. The attribute has a maximum length of KMaxAttributeLength UTF-16 characters.

The attribute is provisioned by the device creator. If the device creator does not provide an attribute value for the given UID then KNullDesC16 will be supplied and KErrNotFound will be returned. If the device creator has supplied an attribute value which is longer than KMaxAttributeLength then the supplied value will be truncated. In this case KErrKErrOverflow will be returned.

Parameter	Description
aAttributeUid	The UID of the required attribute.
aValue	On return, contains the attribute value if successful and KNullDesC16 otherwise.

Returns: KErrNone Successful, the provisioned value has been returned. KErrNotFound A value for the given UID was not provisioned. KErrOverflow The provisioned attribute value has been truncated. - Otherwise, one of the other system-wide error codes.

GetDefaultDeviceName ( TPtrC16 & )

IMPORT_C TInt

GetDefaultDeviceName

(

TPtrC16 &

aValue

)

const

Retrieves a copy of the default Device Name string. This value conveys the default name for the device as might be used for network identification e.g. Bluetooth nickname. The Device Name has a maximum length of KMaxAttributeLength UTF-16 characters.

This is a standard device type information attribute (it is common to all device creators) as such it can be assumed that an attribute value will always be retrieved.

The Default Device Name is provisioned by the device creator. If the device creator does not provide a value for this attribute then a default value will be supplied instead and KDefaultValue will be returned. If the device creator has supplied a value and it is longer than KMaxAttributeLength or the user supplied descriptors length is less than KMaxAttributeLength then the provioned value will be truncated. In this case KErrKErrOverflow will be returned.

Note: This attribute is represented by a UID of 0x1028635C.

Parameter	Description
aValue	On return, contains the Default Device Name.

Returns: KErrNone Successful, the provisioned value has been returned. KDefaultValue Successful, the default value has been returned. KErrOverflow The provisioned attribute value has been truncated. - Otherwise, one of the other system-wide error codes.

GetManufacturerName ( TPtrC16 & )

IMPORT_C TInt

GetManufacturerName

(

TPtrC16 &

aValue

)

const

Retrieves a reference to the Manufacturer Name string. This value conveys the name of the device manufacturer. The Manufacturer Name has a maximum length of KMaxAttributeLength UTF-16 characters.

This is a standard device type information attribute (it is common to all device creators) as such it can be assumed that an attribute value will always be retrieved.

The Manufacturer Name is provisioned by the device creator. If the device creator does not provide a value for this attribute then a default value will be supplied instead and KDefaultValue will be returned. If the device creator has supplied a value and it is longer than KMaxAttributeLength then the provisioned value will be truncated. In this case KErrOverflow will be returned.

Note: This attribute is represented by a UID of 0x10286358.

Parameter	Description
aValue	On return, contains the Manufacturer Name UTF-16 string.

Returns: KErrNone Successful, the provisioned value has been returned. KDefaultValue Successful, the default value has been returned. KErrOverflow The provisioned attribute value has been truncated - Otherwise one of the other system-wide error codes.

GetModelCode ( TPtrC16 & )

IMPORT_C TInt

GetModelCode

(

TPtrC16 &

aValue

)

const

Retrieves a reference to the Model Code string. This value conveys the internal model name or part number by which this model is known to the manufacturer. The Model Code has a maximum length of KMaxAttributeLength UTF-16 characters.

This is a standard device type information attribute (it is common to all device creators) as such it can be assumed that an attribute value will always be retrieved.

The Model Code is provisioned by the device creator. If the device creator does not provide a value for this attribute then a default value will be supplied instead and KDefaultValue will be returned. If the device creator has supplied a value and it is longer than KMaxAttributeLength then the provisioned value will be truncated. In this case KErrKErrOverflow will be returned.

Note: This attribute is represented by a UID of 0x1028635A.

Parameter	Description
aValue	On return, contains the Model Code.

GetModelName ( TPtrC16 & )

IMPORT_C TInt

GetModelName

(

TPtrC16 &

aValue

)

const

Retrieves a reference to the Model Name string. This value conveys the model name of the device as recognisable by the end-user i.e. the consumer. The Model Name has a maximum length of KMaxAttributeLength UTF-16 characters.

This is a standard device type information attribute (it is common to all device creators) as such it can be assumed that an attribute value will always be retrieved.

The Model Name is provisioned by the device creator. If the device creator does not provide a value for this attribute then a default value will be supplied instead and KDefaultValue will be returned. If the device creator has supplied a value and it is longer than KMaxAttributeLength then the provisioned value will be truncated. In this case KErrKErrOverflow will be returned.

Note: This attribute is represented by a UID of 0x10286359.

Parameter	Description
aValue	On return, contains the Model Name.

GetOSVersion ( TPtrC16 & )

IMPORT_C TInt

GetOSVersion

(

TPtrC16 &

aValue

)

const

Retrieves a reference to the Symbian OS version used in the device for display, transmission or tagging purposes. The Symbian OS version has a maximum length of KMaxAttributeLength UTF-16 characters.

The string should never be used for programmatic decisions based on assumed functionality present in the device as device creators can very the content of the device firmware. Instead Feature Manager should be used to query the functional capabilities of a device.

Parameter	Description
aValue	On return, contains the Symbian OS version number.

GetOSVersion ( TUint16 &, TUint16 & )

IMPORT_C TInt	GetOSVersion	(	TUint16 &	aMajor,
			TUint16 &	aMinor
		)	const

Retrieves the Symbian OS major and minor version numbers as TUint16s.

The retrieved values are both standard device type information attributes (they are common to all device creators) as such it can be assumed that values will always be retrieved.

The OS version is provisioned by the device creator. If the device creator provides invalid major and minor UI version numbers the default version numbers will be supplied and KErrCorrupt will be returned. If the device creator does not provide values for these attributes then default values will be supplied and KDefaultValue will be returned.

Note: The major UI version number attribute is represented by a UID of 0x10286361 and minor UI version number is represented by a UID of 0x10286362.

Parameter	Description
aMajor	On return, contains the OS major version number.
aMinor	On return, contains the OS minor version number.

Returns: KErrNone Successful, the provisioned value has been returned. KDefaultValue Successful, the default value has been returned. KErrCorrupt The provisioned attribute value is invalid. The default value has been returned. - Otherwise, one of the other system-wide error codes.

GetRevisionID ( TPtrC16 & )

IMPORT_C TInt

GetRevisionID

(

TPtrC16 &

aValue

)

const

Retrieves a reference to the Revision ID string. This value contains the device revision and/or variant identification string and conveys the specific version of the hardware and software used in the device. The Revision ID has a maximum length of KMaxAttributeLength UTF-16 characters.

This is a standard device type information attribute (it is common to all device creators) as such it can be assumed that an attribute value will always be retrieved.

The Revision ID is provisioned by the device creator. If the device creator does not provide a value for this attribute then a default value will be supplied instead and KDefaultValue will be returned. If the device creator has supplied a value and it is longer than KMaxAttributeLength then the provisioned value will be truncated. In this case KErrKErrOverflow will be returned.

Note: This attribute is represented by a UID of 0x1028635B.

Parameter	Description
aValue	On return, contains the Revision ID (this also includes the Variant ID).

GetUIPlatformName ( TPtrC16 & )

IMPORT_C TInt

GetUIPlatformName

(

TPtrC16 &

aValue

)

const

Retrieves a reference to the name of the UI Platform software used in the device. The UI Platform name has a maximum length of KMaxAttributeLength UTF-16 characters.

This is a standard device type information attribute (it is common to all device creators) as such it can be assumed that an attribute value will always be retrieved.

The UI Platform is provisioned by the device creator. If the device creator does not provide a value for this attribute then a default value will be supplied instead and KDefaultValue will be returned. If the device creator has supplied a value and it is longer than KMaxAttributeLength then the provisioned value will be truncated. In this case KErrKErrOverflow will be returned.

Note: This attribute is represented by a UID of 0x1028635D.

Parameter	Description
aValue	On return, contains the UI Platform.

GetUIPlatformVersion ( TPtrC16 & )

IMPORT_C TInt

GetUIPlatformVersion

(

TPtrC16 &

aValue

)

const

Retrieves a reference to the UI Platform version used in the device for display, transmission or tagging purposes. The UI Platform version has a maximum length of KMaxAttributeLength UTF-16 characters.

The string should never be used for programmatic decisions based on assumed functionality present in the device as device creators can vary the content of the device firmware. Instead Feature Manager should be used to query the functional capabilities of a device.

Parameter	Description
aValue	On return, contains the UI version number of the current UI platform.

GetUIPlatformVersion ( TUint16 &, TUint16 & )

IMPORT_C TInt	GetUIPlatformVersion	(	TUint16 &	aMajor,
			TUint16 &	aMinor
		)	const

Retrieves the UI platform major and minor version numbers as TUint16s.

The retrieved values are both standard device type information attributes (they are common to all device creators) as such it can be assumed that values will always be retrieved.

The UI version is provisioned by the device creator. If the device creator provides invalid major and minor UI version numbers the default version numbers will be supplied and KErrCorrupt will be returned. If the device creator does not provide values for these attributes then default values will be supplied and KDefaultValue will be returned.

Note: The major UI version number attribute is represented by a UID of 0x1028635E and minor UI version number is represented by a UID of 0x1028635F.

Parameter	Description
aMajor	On return, contains the UI major version number.
aMinor	On return, contains the UI minor version number.

NewL ( )

CDeviceTypeInformation *

NewL

(

)

[static]

Allocates and constructs an instance of CDeviceTypeInformation.

leave: KErrNoMemory, if there is not enough memory to create the object.

leave

Otherwise one of the other system-wide error codes.

Returns: A pointer to an instance of CDeviceTypeInformation.