|
1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 /** |
|
17 @file |
|
18 @publishedPartner |
|
19 @released |
|
20 */ |
|
21 |
|
22 #ifndef HCICOMMANDQUEUE_H |
|
23 #define HCICOMMANDQUEUE_H |
|
24 |
|
25 #include <e32def.h> |
|
26 #include <e32cmn.h> |
|
27 |
|
28 |
|
29 class CHCICommandQItem; |
|
30 class MHCICommandQueueClient; |
|
31 class CHCICommandBase; |
|
32 |
|
33 /** |
|
34 An Invalid Command Queue Item Id. |
|
35 */ |
|
36 static const TUint KInvalidCommandQueueItemId = 0; |
|
37 |
|
38 class MHCICommandQueue |
|
39 { |
|
40 public: |
|
41 /** |
|
42 Adds a pre-allocated command item to the end of the command queue. Ownership of the command item |
|
43 is transferred from the caller (even in the event of an ..Add.. method leaving). |
|
44 |
|
45 Use this function if you pre-allocated a CHCICommandQItem. Use this for ensuring |
|
46 that a command can get accepted by the command queue in low memory conditions. |
|
47 |
|
48 @leave KErrHardwareNotAvailable if unable to add the command to the Command Queue due to the controller |
|
49 being in a power off state. |
|
50 |
|
51 @param aQueItem The command queue item to be added to the queue. |
|
52 Ownership is passed. |
|
53 @return the command queue ID given to the command which can be used to remove the command |
|
54 if necessary in future. |
|
55 */ |
|
56 virtual TUint MhcqAddCommandL(CHCICommandQItem* aQueItem) = 0; |
|
57 |
|
58 /** |
|
59 Adds a command to the end of the command queue. Ownership of the command data is transfered from |
|
60 the caller (even in the event of an ..Add.. method leaving). |
|
61 |
|
62 @leave KErrNoMemory This function may leave as it allocates a CHCICommandQItem to wrap around CHCICommandBase. |
|
63 @leave KErrNotSupported if aCommandData is not recognised. E.g. if the caller of the function is |
|
64 asking for a command from a version of the Bluetooth specification |
|
65 that the licensee HCI implementation doesn't support. |
|
66 @leave KErrHardwareNotAvailable if unable to add the command to the Command Queue due to the controller |
|
67 being in a power off state. |
|
68 |
|
69 @param aCommandData The data to be added to a command queue item which will be be placed on the queue. |
|
70 Ownership is passed. |
|
71 @param aCmdProgressRecipient The interface which will get notified about the command's progress. |
|
72 @return the command queue ID given to the command which can be used to remove the command |
|
73 if necessary in future. |
|
74 */ |
|
75 virtual TUint MhcqAddCommandL(CHCICommandBase* aCommandData, MHCICommandQueueClient& aCmdProgressRecipient) = 0; |
|
76 |
|
77 /** |
|
78 Adds a pre-allocated priority command item to the head of the command queue. Ownership of the command item |
|
79 is transferred from the caller (even in the event of an ..Add.. method leaving). |
|
80 |
|
81 Use this function if you pre-allocated a CHCICommandQItem. Use this for ensuring |
|
82 that a command can get accepted by the command queue in low memory conditions. |
|
83 |
|
84 @leave KErrHardwareNotAvailable if unable to add the command to the Command Queue due to the controller |
|
85 being in a power off state. |
|
86 |
|
87 @param aQueItem The command queue item to be added to the queue. |
|
88 Ownership is passed. |
|
89 @return the command queue ID given to the command which can be used to remove the command |
|
90 if necessary in future. |
|
91 */ |
|
92 virtual TUint MhcqAddPriorityCommandL(CHCICommandQItem* aQueItem) = 0; |
|
93 |
|
94 /** |
|
95 Adds a priority command to the head of the command queue. Ownership of the command data is transfered from |
|
96 the caller (even in the event of an ..Add.. method leaving). |
|
97 |
|
98 @leave KErrNoMemory This function may leave as it allocates a CHCICommandQItem to wrap around CHCICommandBase. |
|
99 @leave KErrNotSupported if aCommandData is not recognised. E.g. if the caller of the function is |
|
100 asking for a command from a version of the Bluetooth specification |
|
101 that the licensee HCI implementation doesn't support. |
|
102 @leave KErrHardwareNotAvailable if unable to add the command to the Command Queue due to the controller |
|
103 being in a power off state. |
|
104 |
|
105 @param aCommandData The data to be added to a command queue item which will be be placed on the queue. |
|
106 Ownership is passed. |
|
107 @param aCmdProgressRecipient The interface which will get notified about the command's progress. |
|
108 @return the command queue ID given to the command which can be used to remove the command |
|
109 if necessary in future. |
|
110 */ |
|
111 virtual TUint MhcqAddPriorityCommandL(CHCICommandBase* aCommandData, MHCICommandQueueClient& aCmdProgressRecipient) = 0; |
|
112 |
|
113 /** |
|
114 Adds a pre-allocated initialisation command item to the end of the command queue. Ownership of the command item |
|
115 is transferred from the caller (even in the event of an ..Add.. method leaving). |
|
116 |
|
117 Initialisation commands are only accepted and sent after the Command Queue has |
|
118 been reset but before it has been started. |
|
119 |
|
120 Use this function if you pre-allocated a CHCICommandQItem. Use this for ensuring |
|
121 that a command can get accepted by the command queue in low memory conditions. |
|
122 |
|
123 @see CHCICmdQController::Reset |
|
124 @see CHCICmdQController::Start |
|
125 |
|
126 @leave KErrHardwareNotAvailable if unable to add the command to the Command Queue due to the controller |
|
127 being in a power off state. |
|
128 |
|
129 @panic EInitCmdAfterStart Attempting to add an initialisation command after the queue has been started. |
|
130 |
|
131 @param aQueItem The command queue item to be added to the queue. |
|
132 Ownership is passed. |
|
133 @return the command queue ID given to the command which can be used to remove the command |
|
134 if necessary in future. |
|
135 */ |
|
136 virtual TUint MhcqAddInitCommandL(CHCICommandQItem* aQueItem) = 0; |
|
137 |
|
138 /** |
|
139 Adds an initialisation command to the end of the command queue. Ownership of the command data is transfered from |
|
140 the caller (even in the event of an ..Add.. method leaving). |
|
141 |
|
142 Initialisation commands are only accepted and sent after the Command Queue has |
|
143 been reset but before it has been started. |
|
144 |
|
145 @see CHCICmdQController::Reset |
|
146 @see CHCICmdQController::Start |
|
147 |
|
148 @leave KErrNoMemory This function may leave as it allocates a CHCICommandQItem to wrap around CHCICommandBase. |
|
149 @leave KErrNotSupported if aCommandData is not recognised. E.g. if the caller of the function is |
|
150 asking for a command from a version of the Bluetooth specification |
|
151 that the licensee HCI implementation doesn't support. |
|
152 @leave KErrHardwareNotAvailable if unable to add the command to the Command Queue due to the controller |
|
153 being in a power off state. |
|
154 |
|
155 @panic EInitCmdAfterStart Attempting to add an initialisation command after the queue has been started. |
|
156 |
|
157 @param aCommandData The data to be added to a command queue item which will be be placed on the queue. |
|
158 Ownership is passed. |
|
159 @param aCmdProgressRecipient The interface which will get notified about the command's progress. |
|
160 @return the command queue ID given to the command which can be used to remove the command |
|
161 if necessary in future. |
|
162 */ |
|
163 virtual TUint MhcqAddInitCommandL(CHCICommandBase* aCommandData, MHCICommandQueueClient& aCmdProgressRecipient) = 0; |
|
164 |
|
165 /** |
|
166 Removes the command, which has ID aCommandId, from the queue of commands that haven't been sent to the |
|
167 Bluetooth controller yet. |
|
168 |
|
169 @param aCommandId the ID of the command to remove. |
|
170 @param aCmdOriginator The client that added the command in the first place. This means one client can't |
|
171 remove the commands of another client. |
|
172 @return KErrNotFound if the commmand refered to isn't on the queue of pending commands. This could be |
|
173 because the command has already been sent to the contoller or because no command with the |
|
174 specified ID was added to the command queue via on of the AddCommand methods above. |
|
175 */ |
|
176 virtual TInt MhcqRemoveCommand(TUint aCommandId, const MHCICommandQueueClient& aCmdOriginator) = 0; |
|
177 |
|
178 /** |
|
179 Removes from the Command Queue of all commands a given client has added to the queue. |
|
180 |
|
181 This should always be called by a MHCICommandQueueClient that has added commands to the Command |
|
182 Queue before it is deleted. |
|
183 |
|
184 It should be noted that once this is called: |
|
185 - Commands that are pending and have not yet been sent may never get sent. |
|
186 - Pointers to the CHCICommandQItem may (or may not) be valid. |
|
187 |
|
188 @param aCmdOriginator The client of commands that are to be purged from the Command Queue. |
|
189 */ |
|
190 virtual void MhcqRemoveAllCommands(const MHCICommandQueueClient& aCmdOriginator) = 0; |
|
191 |
|
192 /** |
|
193 @return The maximum timeout that can be returned by MHCICmdQueueDecisionInterface::MhcqdiTimeoutRequired |
|
194 */ |
|
195 virtual TUint MhcqMaxHciCommandTimeout() const = 0; |
|
196 |
|
197 /** |
|
198 This accesses CHCICmdQueueDecisionPlugin::Interface allowing clients of the |
|
199 Command Queue to request additional interfaces from the QDP |
|
200 |
|
201 This function will panic if a client attempts to get hold of |
|
202 MHCICmdQueueDeicisionInterface, which is exclusive to the Command Queue. |
|
203 |
|
204 @see CHCICmdQueueDecisionPlugin::Interface |
|
205 |
|
206 @panic EIllegalRequestForQDPInterface if the client requests MHCICmdQueueDecisionInterface |
|
207 |
|
208 @param aUid UID of interface to request from the QDP |
|
209 @return Result from CHCICmdQueueDecisionPlugin::Interface |
|
210 Note that this can be NULL if there is no QDP in the system |
|
211 */ |
|
212 virtual TAny* MhcqQdpPluginInterface(TUid aUid) const = 0; |
|
213 }; |
|
214 |
|
215 #endif // HCICOMMANDQUEUE_H |
|
216 |