MHCICmdQueueDecisionInterface Class Reference

class MHCICmdQueueDecisionInterface

Mixin for the QDP interface.

This interface is to be used via the Command Queue Decision plugin. CHCICmdQueueDecisionPlugin::Interface(TUid)The QDP is design to help licensees with the following types of workarounds:
  • Automatically resending commands that have completed with an error.

  • Applying a timeout to the period between a command being sent to the controller and the command completing.

  • Adding 'child' commands before and after an existing command that the Command Queue wishes to send.

  • Blocking the next command to be sent from the Command Queue depending on what had already been sent to the controller.

  • Dealing with unexpected events from the controller.

Public Member Functions
TInt MhcqdiCanSend(CHCICommandQItem &, const TDblQue< const CHCICommandQItem > &)
voidMhcqdiCommandAboutToBeDeleted(const CHCICommandQItem &)
TCommandTimedOutAction MhcqdiCommandTimedOut(const CHCICommandQItem &, const TDblQue< const CHCICommandQItem > &, TUint, TUint &)
TBool MhcqdiDoesCommandRequireWorkaround(const CHCICommandQItem &)
THCIEventBase *MhcqdiGetFakedUnsolicitedEvent(const CHCICommandQItem &, const THCIEventBase *)
CHCICommandQItem *MhcqdiGetPostChildCommand(const CHCICommandQItem &, const CHCICommandQItem *, const THCIEventBase *)
CHCICommandQItem *MhcqdiGetPreChildCommand(const CHCICommandQItem &, const CHCICommandQItem *, const THCIEventBase *)
TCommandErroredAction MhcqdiMatchedErrorEventReceived(const THCIEventBase &, const CHCICommandQItem &)
voidMhcqdiMatchedEventReceived(const THCIEventBase &, const CHCICommandQItem &)
TUint MhcqdiReset()
voidMhcqdiSetHCICommandQueue(MHCICommandQueue &)
voidMhcqdiSetHardResetInitiator(const MHardResetInitiator &)
voidMhcqdiSetPhysicalLinksState(const MPhysicalLinksState &)
voidMhcqdiSetTimeouts(TUint, TUint)
TUint MhcqdiTimeoutRequired(const CHCICommandQItem &)
voidMhcqdiUnmatchedEventReceived(const THCIEventBase &)
Public Member Enumerations
enumTCanSendAction { EContinue = KErrNone, EBlock = 1 }
enumTCommandErroredAction { EContinueWithError = 0, EResendErroredCommand = 1 }
enumTCommandTimedOutAction { EDropTimeoutEvent = 0, EContinueWithTimeoutEvent = 1, EResendTimedOutCommand = 2 }
Public Attributes
const TUintKNoTimeoutRequired

Member Functions Documentation

MhcqdiCanSend(CHCICommandQItem &, const TDblQue< const CHCICommandQItem > &)

TInt MhcqdiCanSend(CHCICommandQItem &aCommand,
const TDblQue< const CHCICommandQItem > &aSentCommands
)[pure virtual]

Called when the Command Queue has determined that aCommand is in a position to be sent. This function gives the QDP the opportunity to send, block or reject the command.

If TCanSendAction::EBlock is returned the command will be delayed. MhcqdiCanSend will be called again by the Command Queue after:
  • the sent queue has changed (command completed successfully or with an error)

  • an unsolicited event has been received (e.g. PIN Code Request Event) The QDP gets a chance to let the command be sent or to delay it further. There is no other way (e.g. by a call back into the Command Queue) for the QDP to change its mind and decide a command can be sent.

The QDP should be careful not to cause a deadlock. This could happen if the decision is taken not to send command A if the command P is in the sent queue. However, if the completion of P depends on command A then the Command Queue would deadlock. For example, P = Connection Request Command and A = PIN Request Reply Command (in secmode 3).

To aid in avoiding deadlocks the Command Queue:
  • will ASSERT the sent queue is not empty if CanSend returns TCanSendAction::EBlock

  • will run a watchdog timer to ensure the queue is not being starved

CanSend can return a Symbian error code (not including KErrNone) to tell the Command Queue not to send a command. The obtained error code is send back to the command's originator. HCI error codes are represented within the Symbian error code range by subtracting the Bluetooth specification defined error code from KHCIErrorBase.

Returning KErrNone will result in the command being sent.

Note that the Command Queue will panic if the value returned is not a Symbian system-wide error code, a Symbian HCI error code (excluding EOK), or TCanSendAction::EBlock.

panic
ECanSendDeadlock if queue starvation watchdog timer fires as a result of a CanSend block In release urel builds a controller reset will be started
panic
EResendDeadlock if queue starvation watchdog timer fires as a result of a Resend block In release urel builds a controller reset will be started
panic
EUnknownDeadlock if queue starvation watchdog timer fires and the cause cannot be determined In release urel builds a controller reset will be started
panic
ECanSendBlockWhenEmpty if the QDP blocks with an empty sent queue
panic
ECanSendInvalidRejectError if the value returned is not in the ranges expected.

Parameters

CHCICommandQItem & aCommandThe command to decide whether it should be delayed (or not).
const TDblQue< const CHCICommandQItem > & aSentCommandsThese are the commands that have been sent to the controller but haven't been completed yet.

MhcqdiCommandAboutToBeDeleted(const CHCICommandQItem &)

voidMhcqdiCommandAboutToBeDeleted(const CHCICommandQItem &aDyingCmd)[pure virtual]

Called immediately prior to a command queue item being deleted to allow the QDP to clean up the items QDP data member.

Parameters

const CHCICommandQItem & aDyingCmdThe CHCICommandQItem that should have its QDP data member cleaned up.

MhcqdiCommandTimedOut(const CHCICommandQItem &, const TDblQue< const CHCICommandQItem > &, TUint, TUint &)

TCommandTimedOutAction MhcqdiCommandTimedOut(const CHCICommandQItem &aCommand,
const TDblQue< const CHCICommandQItem > &aSentCommands,
TUintaCurrentCommandCredits,
TUint &aCreditsToBeRefunded
)[pure virtual]

Called when the timeout for a command has expired.

TCommandTimedOutAction

Parameters

const CHCICommandQItem & aCommandThe command that has timed out.
const TDblQue< const CHCICommandQItem > & aSentCommandsThe list of commands currently on the Sent Queue.
TUint aCurrentCommandCreditsThe current number of command credits available to the Command Queue.
TUint & aCreditsToBeRefundedThe number of credits to be refunded to the command queue.

MhcqdiDoesCommandRequireWorkaround(const CHCICommandQItem &)

TBool MhcqdiDoesCommandRequireWorkaround(const CHCICommandQItem &aParent)[pure virtual]

Queries whether a HCI command requires child commands to be sent before or after this parent command is sent for a workaround.

Parameters

const CHCICommandQItem & aParentThe command that might require a workaround.

MhcqdiGetFakedUnsolicitedEvent(const CHCICommandQItem &, const THCIEventBase *)

THCIEventBase *MhcqdiGetFakedUnsolicitedEvent(const CHCICommandQItem &aParent,
const THCIEventBase *aPreviousFakedEvent
)[pure virtual]

Retrieves the next faked event the QDP wishes to send (following a workaround) in order for it to keep the Stack synchronised with what may have been done (normally in the case where state cannot returned to how it was prior to the workaround, i.e. failures to succesfully perform the post-workaround stage)

For a faked event to be sent, the QDP should create a descriptor (of sufficient lifetime) that contains the raw data the event is to have. It should then use this to create an appropriate THCIEventBase class, which is to be returned as the faked event for the Command Queue to pass on.

This function will be repeatedly called (while the QDP continues to return faked events) so as to retrieve the sequence of faked events required. The previous faked event will be provided in the call to the QDP so that it does not need to maintain state about how far though the sequence of faked events it is.

When there are no (more) faked events required, a NULL pointer should be returned.

Parameters

const CHCICommandQItem & aParentThe parent command that requires fake events to be generated.
const THCIEventBase * aPreviousFakedEventWill be NULL the first time this function is caled for a particular workaround, otherwise it will point to an identical instance of the previously faked event generated by the QDP. Ownership is not passed.

MhcqdiGetPostChildCommand(const CHCICommandQItem &, const CHCICommandQItem *, const THCIEventBase *)

CHCICommandQItem *MhcqdiGetPostChildCommand(const CHCICommandQItem &aParent,
const CHCICommandQItem *aPreviousPostChild,
const THCIEventBase *aPreviousCmdResult
)[pure virtual]

Retrieves the next post-child command for a parent command. A post-child command is a command that is to be sent to the HCTL after the parent command has been sent.

The aid the QDP in selecting the next command to be sent, it is passed the parent command and pointers to the previous child-command sent and its associated event. Note if the same command needs to be sent twice in a workaround, the QDP needs to create two different objects, as ownership of the resultant command is passed to the Command Queue.

Parameters

const CHCICommandQItem & aParentThe parent command that the post-child command would be for.
const CHCICommandQItem * aPreviousPostChildWill be NULL the first time this function is called for a particular workaround. Ownership is not passed.
const THCIEventBase * aPreviousCmdResultIf aPreviousPostChild is NULL then this is the result of aParent otherwise it is the result of aPreviousPostChild. This parameter can be NULL if the previous command timed out (so there is no event). Ownership is not passed.

MhcqdiGetPreChildCommand(const CHCICommandQItem &, const CHCICommandQItem *, const THCIEventBase *)

CHCICommandQItem *MhcqdiGetPreChildCommand(const CHCICommandQItem &aParent,
const CHCICommandQItem *aPreviousWorkaroundCmd,
const THCIEventBase *aPreviousCmdResult
)[pure virtual]

Retrieves the next pre-child command for a parent command. A pre-child command is a command that is to be sent to the HCTL before the parent command is sent.

The aid the QDP in selecting the next command to be sent, it is passed the parent command and pointers to the previous child-command sent and its associated event. Note if the same command needs to be sent twice in a workaround, the QDP needs to create two different objects, as ownership of the resultant command is passed to the Command Queue.

Parameters

const CHCICommandQItem & aParentThe parent command that the pre-child command will be for.
const CHCICommandQItem * aPreviousWorkaroundCmdWill be null the first time this function is called for a particular workaround. Ownership is not passed.
const THCIEventBase * aPreviousCmdResultWill be null the first time this function is called for a particular workaround or if the previous command has timed out (so there is no event). Ownership is not passed.

MhcqdiMatchedErrorEventReceived(const THCIEventBase &, const CHCICommandQItem &)

TCommandErroredAction MhcqdiMatchedErrorEventReceived(const THCIEventBase &aErrorEvent,
const CHCICommandQItem &aRelatedCommand
)[pure virtual]

Called to notify the QDP of an event that has been matched to a command. This function is intended as a way of the QDP keeping its state up-to-date. TCommandErroredAction

Parameters

const THCIEventBase & aErrorEventThe event received which represents an error.
const CHCICommandQItem & aRelatedCommandThe command that caused the event.

MhcqdiMatchedEventReceived(const THCIEventBase &, const CHCICommandQItem &)

voidMhcqdiMatchedEventReceived(const THCIEventBase &aEvent,
const CHCICommandQItem &aRelatedCommand
)[pure virtual]

Called to notify the QDP of an event that has been matched to a command. This function is intended only as a way of the QDP keeping its state up-to-date.

Parameters

const THCIEventBase & aEventThe event received.
const CHCICommandQItem & aRelatedCommandThe command that caused the event.

MhcqdiReset()

TUint MhcqdiReset()[pure virtual]

Notifies the QDP of the Command Queue being reset.

This returns the initial number of command credits for the queue, which is typically one. However, some controllers send an event after reset to set credits so it could be zero.

MhcqdiSetHCICommandQueue(MHCICommandQueue &)

voidMhcqdiSetHCICommandQueue(MHCICommandQueue &aHCICommandQueue)[pure virtual]

Gives the QDP a reference to MHCICommandQueue, which allows it to add and remove commands when necessary

Parameters

MHCICommandQueue & aHCICommandQueueInterface to Command Queue

MhcqdiSetHardResetInitiator(const MHardResetInitiator &)

voidMhcqdiSetHardResetInitiator(const MHardResetInitiator &aHardResetInitiator)[pure virtual]

Gives the QDP a reference to MHardResetInitiator, which allows it to initiate a hard reset

Parameters

const MHardResetInitiator & aHardResetInitiatorHard Reset interface to use

MhcqdiSetPhysicalLinksState(const MPhysicalLinksState &)

voidMhcqdiSetPhysicalLinksState(const MPhysicalLinksState &aPhysicalLinksState)[pure virtual]

Gives the QDP a reference to MPhysicalLinksState, which provides information that helps with decision making.

Parameters

const MPhysicalLinksState & aPhysicalLinksStateInterface to query the state of the stack's physical links

MhcqdiSetTimeouts(TUint, TUint)

voidMhcqdiSetTimeouts(TUintaQueueStarvationTimeout,
TUintaMaxHciCommandTimeout
)[pure virtual]

The QDP should make use of these values when informing the command queue of command completion timeouts. The QDP should be aware when choosing command completion timeouts, that choosing a value approaching the starvation timeout may result in panicing the queue. By default KMaxHciCommandTimeout is less than KQueueStarvationTimeout although this is configurable via the CmdQ.ini file. MhcqdiTimeoutRequired

Parameters

TUint aQueueStarvationTimeoutThe time (in milliseconds) in which the Command Queues starvation timer will fire if the pending queue head has remained unchanged.
TUint aMaxHciCommandTimeoutThe maximum timeout value the qdp may provide for command completion. See MhcqdiTimeoutRequired().

MhcqdiTimeoutRequired(const CHCICommandQItem &)

TUint MhcqdiTimeoutRequired(const CHCICommandQItem &aSentCmd)[pure virtual]

Called immediately after a command has been sent to the controller allowing the QDP to keep its state up-to-date and specify a time-out for the command.

panic
ECommandTimeoutTooBig if the TUint returned is greater than MHCICommandQueue::MaxHciCommandTimeout().
KNoTimeoutRequired

Parameters

const CHCICommandQItem & aSentCmdThe sent command.

MhcqdiUnmatchedEventReceived(const THCIEventBase &)

voidMhcqdiUnmatchedEventReceived(const THCIEventBase &aEvent)[pure virtual]

Called to notify the QDP of an event that does not have a matching command. This function is intended as a way of the QDP keeping its state up-to-date.

Note that this function will be called for both events that could legitimately be unexpected (unsolicited events), and those that are due to the controller sending us something odd e.g. providing a command status event for a command that has not been sent.

Parameters

const THCIEventBase & aEventThe event received.

Member Enumerations Documentation

Enum TCanSendAction

Represents the action that the QDP decides the Command Queue should take when a command is presented to the QDP ready to be sent, in the MhcqdiCanSend function. MhcqdiCanSend

Enumerators

EContinue = KErrNone

Send the command, identical to KErrNone

EBlock = 1

Delay sending the command.

Enum TCommandErroredAction

Represents the action that the QDP decides the Command Queue should take when a command is matched to an event which signifies an error. MhcqdiMatchedErrorEventReceived

Enumerators

EContinueWithError = 0

Continue and report the error to the client who added the command.

EResendErroredCommand = 1

Attempt to resend the command (command's client is not informed).

Enum TCommandTimedOutAction

Represents the action that the QDP decides the Command Queue should take when the timeout for a command has expired. MhcqdiCommandTimedOut

Enumerators

EDropTimeoutEvent = 0

Do not inform the command's client of the timeout. This will result in the command being dropped. A QDP would wish to do this if it reset the controller in the MhcqdiCommandTimedOut function call.

EContinueWithTimeoutEvent = 1

Continue as if it had received an event with error code EHardwareFail.

EResendTimedOutCommand = 2

Attempt to resend the command (command's client is not informed).

Member Data Documentation

const TUint KNoTimeoutRequired

const TUintKNoTimeoutRequired[static]

Represents that no timer is required for the completion of a command.