Class RBusLogicalChannel

RDevice

Support

Supported from 5.0

Description

User side handle to a logical channel.

A channel handle is owned by the thread that opens that channel. The handle cannot be shared with other threads.

Derivation

MBusDev   RBusLogicalChannel User side handle to a logical channel RHandleBase A handle to an object

Defined in RBusLogicalChannel:
CheckBusStatus(), DoCancel(), DoCheckBusStatus(), DoControl(), DoCreate(), DoRequest(), DoSvControl()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

See also:

• DLogicalChannel

protected : TInt DoCreate(const TDesC& aDevice,const TVersion& aVer,const TDesC* aChan,TInt aUnit,const TDesC* aDriver,const TDesC8* anInfo,TOwnerType aType=EOwnerProcess);

Description

Creates the logical channel for the current thread.

The logical channel is an instance of a DLogicalChannel derived class, a Kernel side object that is created on the Kernel heap and is associated with one, and only one thread.

The function checks whether asynchronous operations are needed before and/or after opening the logical channel. This is implemented as a Kernel Executive type call and results in every installed DPhysicalDevice object associated with this logical device being interrogated through a call to DPhysicalDevice::CheckForSlowOpening(). If needed, the function starts the asynchronous operation and waits for its completion before starting the process of creating the logical channel.

The function then makes a Kernel server call to implement the creation of the logical channel and this proceeds as follows:

• the Kernel finds the LDD factory object, the instance of the DLogicalDevice derived class, by its full name

• if the LDD factory object requires a PDD, i.e the KDeviceAllowPhysicalDevice flag is set in the iParseMask data member of the LDD factory object, then an attempt is made to create a physical channel for an appropriate physical device (or devices). This involves a call to the PDD factory object's DPhysicalDevice::CreateL()

• the LDD factory object's DLogicalDevice::CreateL() is called to construct the logical channel, an instance of a DLogicalChannel derived class

• the Kernel sets the name of the logical channel object to that supplied in the const TDesC* aChan argument

• the owner of the logical channel object is set to either the current process or the current thread according to the value of the TOwnerType aType argument

• the logical channel's DLogicalChannel::DoCreateL(), which, typically does any required secondary initialisation; for example, creating and registering a power handler

• the Kernel adds the channel to its container of logical channels

• the Kernel creates a handle to the channel, i.e. it adds the logical channel to the process's object index or the thread's object index. It is the handle number generated by this operation which is returned to the User side and is encapsulated by this RBusLogicalChannel object.

• the Kernel then returns control to this function.

If necessary, after creating the logical channel, then the function starts another asynchronous operation and waits for its completion.

Parameters

const TDesC& aDevice The name of the logical device for which the channel is to be constructed. This is the name by which the LDD factory object, i.e. the instance of the DLogicalDevice derived class, is known. const TVersion& aVer The required version of the logical device. const TDesC* aChan A pointer to a descriptor containing the name to be assigned to the logical channel; this is optional. If required, it must be a valid reference counting object name. If not required, pass Null; the object will have no name. TInt aUnit A unit of the device. This argument only has meaning if the KDeviceAllowUnit flag is set in the iParseMask protected data member of the LDD factory object, the DLogicalDevice; the value cannot be greater than KMaxUnits, otherwise a KERN-SVR 11 panic is raised. If the KDeviceAllowUnit flag is not set, then this must contain the value KNullUnit, otherwise a KERN-SVR 11 panic is raised. Note that the device driver framework does not define the meaning of a unit. const TDesC* aDriver A pointer to a descriptor containing the fullname of the physical device. The name must be of the form xxx.*, where xxx is the name of the logical device. This argument only has meaning if the logical device needs a physical device, i.e. if the KDeviceAllowPhysicalDevice flag is set in the iParseMask protected data member of the LDD factory object, the DLogicalDevice. If Null, then the Kernel attempts to create a physical channel on all installed physical devices whose name matches xxx.* until a physical channel is successfully created or until attempts on all installed physical channels have failed (causing KerrNotSupported to be returned. const TDesC8* anInfo A pointer to an explicit 8 bit descriptor containing extra information for the device. This argument only has meaning if the KDeviceAllowInfo flag is set in the iParseMask protected data member of the LDD factory object, the DlogicalDevice. Note that the device driver framework does not define the meaning of this infomation. TOwnerType aType An enumeration whose enumerators define the ownership of this handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

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

Notes:

• In practice, LDD and PDD factory objects, i.e. instances of the Kernel side DLogicalDevice and DPhysicalDevice derived classes, which are created on the Kernel heap, have no owner. Their fullnames are, therefore, the same as their names.
• The unit aUnit, the pointer to the extra information anInfo and the version aVer are all forwarded to the function which creates the physical channel, DPhysicalDevice::CreateL().

See also:

• DLogicalChannel
• DLogicalDevice
• DPhysicalDevice
• CObject

protected : void DoRequest(TInt aReqNo,TRequestStatus& aStatus);
protected : void DoRequest(TInt aReqNo,TRequestStatus& aStatus,TAny* a1);
protected : void DoRequest(TInt aReqNo,TRequestStatus& aStatus,TAny* a1,TAny* a2);

Description

Makes an asynchronous Kernel Executive type request to the logical channel.

Before handling the request, a Kernel Executive call is made to ensure that the device is still powered up. If it is not powered up, then the asynchronous operations performed before and/or after creation of the logical channel are done again.

On the Kernel side, the request is handled by the logical channel's DLogicalChannel::Request() function.

When the request completes, the request status object contains the completion status and the thread's request semaphore is signalled to indicate that the request is complete.

The logical channel can have up to KMaxRequests requests outstanding at any one time. Each request is identified by the value presented by the TInt aReqNo argument and must be associated with a different TRequestStatus object.

Parameters

TInt aReqNo A number identifying the request to the logical channel. The number must be a value in the range 0 to (KMaxRequests-1) inclusive otherwise a KERN-EXEC 10 panic is raised. The number must also be valid as set by a call to DLOgicalChannel::SetBehaviour(), otherwise a KERN-EXEC 10 panic is raised. If a request associated with this number is still outstanding, then a KERN-EXEC 9 panic is raised. The highest four bits can be used to define device specific flags. The constant KChanRequestNoReservedMask defines these four bits. TRequestStatus& aStatus The request status used to completion information for the request. On successful completion, this is set to KErrNone. TAny* a1 If specified, a parameter to be passed to the logical channel. TAny* a2 If specified, a parameter to be passed to the logical channel.

Notes:

• A logical channel is associated with one, and only one thread. The thread, issuing this request, must be the same thread that created the logical channel, otherwise a KERN-EXEC 18 panic is raised.

See also:

• DLogicalChannel::Request()

protected : void DoCancel(TUint aReqMask);

Description

Cancels one or more outstanding asynchronous Kernel Executive type requests to the logical channel.

All outstanding requests complete with KErrCancel.

Parameters

TUint aReqMask A set of bits identifying the requests to be cancelled: bit 0x0001 corresponds to request number 0, bit 0x0002 corresponds to request number 1, bit 0x0004 corresponds to request number 2 etc. The request numbers are those specified in the original call to DoRequest().

See also:

• DoRequest()
• DLogicalChannel::SetBehaviour()

protected : TInt DoControl(TInt aFunction);
protected : TInt DoControl(TInt aFunction,TAny* a1);
protected : TInt DoControl(TInt aFunction,TAny* a1,TAny* a2);

Description

Makes a synchronous Kernel Executive type request to the logical channel.

Before handling the request, a Kernel Executive call is made to ensure that the device is still powered up. If it is not powered up, then the asynchronous operations performed before and/or after creation of the logical channel are done again.

On the Kernel side, the request is handled by the logical channel's DLogicalChannel::Control() function.

Parameters

TInt aFunction A number identifying specific functionality. TAny* a1 If specified, a parameter to be passed to the logical channel; may be Null. TAny* a2 If specified, a parameter to be passed to the logical channel; may be Null.

Return value

TInt KErrNone, if successful, otherwise one of the other system wide error codes. The value returned depends on the implementation of DLogicalChannel::DoControl().

See also:

• DLogicalChannel::Control()
• DLogicalChannel::DoControl()

protected : TInt DoSvControl(TInt aFunction);
protected : TInt DoSvControl(TInt aFunction,TAny *a1);
protected : TInt DoSvControl(TInt aFunction,TAny *a1,TAny *a2);

Description

Makes a synchronous Kernel Server type request to the logical channel.

Before handling the request, a Kernel Executive call is made to ensure that the device is still powered up. If it is not powered up, then the asynchronous operations performed before and/or after creation of the logical channel are done again.

On the Kernel side, the request is handled by the logical channel's DLogicalChannel::Control() function which runs in the context of the Kernel Server.

Parameters

TInt aFunction A number identifying specific functionality. TAny* a1 If specified, a parameter to be passed to the logical channel; may be Null. TAny* a2 If specified, a parameter to be passed to the logical channel; may be Null.

Return value

TInt KErrNone, if successful, otherwise one of the other system wide error codes. The value returned depends on the implementation of DLogicalChannel::DoControl().

See also:

• DLogicalChannel::Control()
• DLogicalChannel::DoControl()

private : TInt CheckBusStatus();

Description

This is internal and is not intended for use.

Return value

TInt No description

private : TInt DoCheckBusStatus(TInt aSocket);

Description

This is internal and is not intended for use.

Parameters

TInt aSocket No description

Return value

TInt No description