xref: /btstack/src/classic/avrcp_controller.h (revision a7d2a6bfacdd4128e009c96c5a832c088cc40706)
1  /*
2   * Copyright (C) 2016 BlueKitchen GmbH
3   *
4   * Redistribution and use in source and binary forms, with or without
5   * modification, are permitted provided that the following conditions
6   * are met:
7   *
8   * 1. Redistributions of source code must retain the above copyright
9   *    notice, this list of conditions and the following disclaimer.
10   * 2. Redistributions in binary form must reproduce the above copyright
11   *    notice, this list of conditions and the following disclaimer in the
12   *    documentation and/or other materials provided with the distribution.
13   * 3. Neither the name of the copyright holders nor the names of
14   *    contributors may be used to endorse or promote products derived
15   *    from this software without specific prior written permission.
16   * 4. Any redistribution, use, or modification is done solely for
17   *    personal benefit and not for any commercial purpose or for
18   *    monetary gain.
19   *
20   * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS
21   * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23   * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BLUEKITCHEN
24   * GMBH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
26   * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
27   * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28   * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
30   * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31   * SUCH DAMAGE.
32   *
33   * Please inquire about commercial licensing options at
34   * contact@bluekitchen-gmbh.com
35   *
36   */
37  
38  /**
39   * @title AVRCP Controller
40   *
41   */
42  
43  #ifndef AVRCP_CONTROLLER_H
44  #define AVRCP_CONTROLLER_H
45  
46  #include <stdint.h>
47  #include "btstack_run_loop.h"
48  #include "btstack_linked_list.h"
49  #include "classic/avrcp.h"
50  
51  #if defined __cplusplus
52  extern "C" {
53  #endif
54  
55  /* API_START */
56  
57  typedef enum {
58      AVRCP_CONTROLLER_SUPPORTED_FEATURE_CATEGORY_PLAYER_OR_RECORDER = 0,
59      AVRCP_CONTROLLER_SUPPORTED_FEATURE_CATEGORY_MONITOR_OR_AMPLIFIER,
60      AVRCP_CONTROLLER_SUPPORTED_FEATURE_CATEGORY_TUNER,
61      AVRCP_CONTROLLER_SUPPORTED_FEATURE_CATEGORY_MENU,
62      AVRCP_CONTROLLER_SUPPORTED_FEATURE_RESERVED_4,
63      AVRCP_CONTROLLER_SUPPORTED_FEATURE_RESERVED_5,
64      AVRCP_CONTROLLER_SUPPORTED_FEATURE_BROWSING,
65      AVRCP_CONTROLLER_SUPPORTED_FEATURE_COVER_ART_GET_IMAGE_PROPERTIES,
66      AVRCP_CONTROLLER_SUPPORTED_FEATURE_COVER_ART_GET_IMAGE,
67      AVRCP_CONTROLLER_SUPPORTED_FEATURE_COVER_ART_GET_LINKED_THUMBNAIL
68  } avrcp_controller_supported_feature_t;
69  
70  /**
71   * @brief AVRCP Controller service record.
72   * @param service
73   * @param service_record_handle
74   * @param supported_features 16-bit bitmap, see AVRCP_FEATURE_MASK_* in avrcp.h
75   * @param service_name or NULL for default value. Provide "" (empty string) to skip attribute
76   * @param service_provider_name or NULL for default value. Provide "" (empty string) to skip attribute
77   */
78  void avrcp_controller_create_sdp_record(uint8_t * service, uint32_t service_record_handle, uint16_t supported_features, const char * service_name, const char * service_provider_name);
79  
80  /**
81   * @brief Set up AVRCP Controller service.
82   */
83  void avrcp_controller_init(void);
84  
85  /**
86   * @brief Register callback for the AVRCP Controller client.
87   * @param callback
88   */
89  void avrcp_controller_register_packet_handler(btstack_packet_handler_t callback);
90  
91  /**
92   * @brief Set max num fragments in whuch message can be transmited.
93   * @param avrcp_cid
94   * @param max_num_fragments
95   * @return status
96   */
97  uint8_t avrcp_controller_set_max_num_fragments(uint16_t avrcp_cid, uint8_t max_num_fragments);
98  
99  
100  /**
101   * @brief Unit info.
102   * @param avrcp_cid
103   * @return status
104   */
105  uint8_t avrcp_controller_unit_info(uint16_t avrcp_cid);
106  
107  /**
108   * @brief Subunit info.
109   * @param avrcp_cid
110   * @return status
111   */
112  uint8_t avrcp_controller_subunit_info(uint16_t avrcp_cid);
113  
114  /**
115   * @brief Get capabilities.
116   * @param avrcp_cid
117   * @return status
118   */
119  uint8_t avrcp_controller_get_supported_company_ids(uint16_t avrcp_cid);
120  
121  /**
122   * @brief Get supported Events.
123   * @param avrcp_cid
124   * @return status
125   */
126  uint8_t avrcp_controller_get_supported_events(uint16_t avrcp_cid);
127  
128  
129  /**
130   * @brief Start continuous cmd (play, pause, volume up, ...). Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
131   * @param avrcp_cid
132   * @return status
133   */
134  uint8_t avrcp_controller_start_press_and_hold_cmd(uint16_t avrcp_cid, avrcp_operation_id_t operation_id);
135  
136  /**
137   * @brief Stops continuous cmd (play, pause, volume up, ...). Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
138   * @param avrcp_cid
139   * @return status
140   */
141  uint8_t avrcp_controller_release_press_and_hold_cmd(uint16_t avrcp_cid);
142  
143  /**
144   * @brief Play. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
145   * @param avrcp_cid
146   * @return status
147   */
148  uint8_t avrcp_controller_play(uint16_t avrcp_cid);
149  uint8_t avrcp_controller_press_and_hold_play(uint16_t avrcp_cid);
150  
151  /**
152   * @brief Stop. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
153   * @param avrcp_cid
154   * @return status
155   */
156  uint8_t avrcp_controller_stop(uint16_t avrcp_cid);
157  uint8_t avrcp_controller_press_and_hold_stop(uint16_t avrcp_cid);
158  
159  /**
160   * @brief Pause. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
161   * @param avrcp_cid
162   * @return status
163   */
164  uint8_t avrcp_controller_pause(uint16_t avrcp_cid);
165  uint8_t avrcp_controller_press_and_hold_pause(uint16_t avrcp_cid);
166  
167  /**
168   * @brief Single step - fast forward. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
169   * @param avrcp_cid
170   * @return status
171   */
172  uint8_t avrcp_controller_fast_forward(uint16_t avrcp_cid);
173  uint8_t avrcp_controller_press_and_hold_fast_forward(uint16_t avrcp_cid);
174  
175  
176  /**
177   * @brief Single step rewind. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
178   * @param avrcp_cid
179   * @return status
180   */
181  uint8_t avrcp_controller_rewind(uint16_t avrcp_cid);
182  uint8_t avrcp_controller_press_and_hold_rewind(uint16_t avrcp_cid);
183  
184  /**
185   * @brief Forward. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
186   * @param avrcp_cid
187   * @return status
188   */
189  uint8_t avrcp_controller_forward(uint16_t avrcp_cid);
190  uint8_t avrcp_controller_press_and_hold_forward(uint16_t avrcp_cid);
191  
192  /**
193   * @brief Backward. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
194   * @param avrcp_cid
195   * @return status
196   */
197  uint8_t avrcp_controller_backward(uint16_t avrcp_cid);
198  uint8_t avrcp_controller_press_and_hold_backward(uint16_t avrcp_cid);
199  
200  /**
201   * @brief Turns the volume to high. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
202   * @param avrcp_cid
203   * @return status
204   */
205  uint8_t avrcp_controller_volume_up(uint16_t avrcp_cid);
206  uint8_t avrcp_controller_press_and_hold_volume_up(uint16_t avrcp_cid);
207  /**
208   * @brief Turns the volume to low. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
209   * @param avrcp_cid
210   * @return status
211   */
212  uint8_t avrcp_controller_volume_down(uint16_t avrcp_cid);
213  uint8_t avrcp_controller_press_and_hold_volume_down(uint16_t avrcp_cid);
214  
215  /**
216   * @brief Puts the sound out. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
217   * @param avrcp_cid
218   * @return status
219   */
220  uint8_t avrcp_controller_mute(uint16_t avrcp_cid);
221  uint8_t avrcp_controller_press_and_hold_mute(uint16_t avrcp_cid);
222  
223  // Basic Group Navigation
224  /**
225   * @brief Move to the first song in the next group.
226   * @param avrcp_cid
227   */
228  uint8_t avrcp_controller_next_group(uint16_t avrcp_cid);
229  
230  /**
231   * @brief Move to the first song in the previous group.
232   * @param avrcp_cid
233   */
234  uint8_t avrcp_controller_previous_group(uint16_t avrcp_cid);
235  
236  // Category 3
237  uint8_t avrcp_controller_0(uint16_t avrcp_cid);
238  uint8_t avrcp_controller_1(uint16_t avrcp_cid);
239  uint8_t avrcp_controller_2(uint16_t avrcp_cid);
240  uint8_t avrcp_controller_3(uint16_t avrcp_cid);
241  uint8_t avrcp_controller_4(uint16_t avrcp_cid);
242  uint8_t avrcp_controller_5(uint16_t avrcp_cid);
243  uint8_t avrcp_controller_6(uint16_t avrcp_cid);
244  uint8_t avrcp_controller_7(uint16_t avrcp_cid);
245  uint8_t avrcp_controller_8(uint16_t avrcp_cid);
246  uint8_t avrcp_controller_9(uint16_t avrcp_cid);
247  uint8_t avrcp_controller_dot(uint16_t avrcp_cid);
248  uint8_t avrcp_controller_enter(uint16_t avrcp_cid);
249  uint8_t avrcp_controller_clear(uint16_t avrcp_cid);
250  uint8_t avrcp_controller_channel_up(uint16_t avrcp_cid);
251  uint8_t avrcp_controller_channel_down(uint16_t avrcp_cid);
252  uint8_t avrcp_controller_previous_channel(uint16_t avrcp_cid);
253  uint8_t avrcp_controller_sound_select(uint16_t avrcp_cid);
254  uint8_t avrcp_controller_input_select(uint16_t avrcp_cid);
255  uint8_t avrcp_controller_display_information(uint16_t avrcp_cid);
256  uint8_t avrcp_controller_help(uint16_t avrcp_cid);
257  uint8_t avrcp_controller_power(uint16_t avrcp_cid);
258  uint8_t avrcp_controller_angle(uint16_t avrcp_cid);
259  uint8_t avrcp_controller_subpicture(uint16_t avrcp_cid);
260  uint8_t avrcp_controller_F1(uint16_t avrcp_cid);
261  uint8_t avrcp_controller_F2(uint16_t avrcp_cid);
262  uint8_t avrcp_controller_F3(uint16_t avrcp_cid);
263  uint8_t avrcp_controller_F4(uint16_t avrcp_cid);
264  uint8_t avrcp_controller_F5(uint16_t avrcp_cid);
265  
266  // Category 4
267  uint8_t avrcp_controller_select(uint16_t avrcp_cid);
268  uint8_t avrcp_controller_up(uint16_t avrcp_cid);
269  uint8_t avrcp_controller_down(uint16_t avrcp_cid);
270  uint8_t avrcp_controller_left(uint16_t avrcp_cid);
271  uint8_t avrcp_controller_right(uint16_t avrcp_cid);
272  uint8_t avrcp_controller_right_up(uint16_t avrcp_cid);
273  uint8_t avrcp_controller_right_down(uint16_t avrcp_cid);
274  uint8_t avrcp_controller_left_up(uint16_t avrcp_cid);
275  uint8_t avrcp_controller_left_down(uint16_t avrcp_cid);
276  uint8_t avrcp_controller_root_menu(uint16_t avrcp_cid);
277  uint8_t avrcp_controller_setup_menu(uint16_t avrcp_cid);
278  uint8_t avrcp_controller_contents_menu(uint16_t avrcp_cid);
279  uint8_t avrcp_controller_favorite_menu(uint16_t avrcp_cid);
280  uint8_t avrcp_controller_exit(uint16_t avrcp_cid);
281  uint8_t avrcp_controller_page_up(uint16_t avrcp_cid);
282  uint8_t avrcp_controller_page_down(uint16_t avrcp_cid);
283  /**
284   * @brief Get play status. Returns event of type AVRCP_SUBEVENT_PLAY_STATUS (length, position, play_status).
285   * If TG does not support SongLength And SongPosition on TG, then TG shall return 0xFFFFFFFF.
286   * @param avrcp_cid
287   * @return status
288   */
289  uint8_t avrcp_controller_get_play_status(uint16_t avrcp_cid);
290  
291  /**
292   * @brief Enable notification. Response via AVRCP_SUBEVENT_NOTIFICATION_STATE.
293   * @param avrcp_cid
294   * @param event_id
295   * @return status
296   */
297  uint8_t avrcp_controller_enable_notification(uint16_t avrcp_cid, avrcp_notification_event_id_t event_id);
298  
299  /**
300   * @brief Disable notification. Response via AVRCP_SUBEVENT_NOTIFICATION_STATE.
301   * @param avrcp_cid
302   * @param event_id
303   * @return status
304   */
305  uint8_t avrcp_controller_disable_notification(uint16_t avrcp_cid, avrcp_notification_event_id_t event_id);
306  
307  /**
308   * @brief Get info on now playing media using subset of attribute IDs
309   * @param avrcp_cid
310   * @return status
311   */
312  uint8_t avrcp_controller_get_element_attributes(uint16_t avrcp_cid, uint8_t num_attributes, avrcp_media_attribute_id_t * attributes);
313  
314  /**
315   * @brief Get info on now playing media using all IDs.
316   * @param avrcp_cid
317   * @return status
318   */
319  uint8_t avrcp_controller_get_now_playing_info(uint16_t avrcp_cid);
320  
321  /**
322   * @brief Get info on now playing media using specific media attribute ID.
323   * @param media_attribute_id
324   * @param avrcp_cid
325   * @return status
326   */
327  uint8_t avrcp_controller_get_now_playing_info_for_media_attribute_id(uint16_t avrcp_cid, avrcp_media_attribute_id_t media_attribute_id);
328  
329  /**
330   * @brief Set absolute volume 0-127 (corresponds to 0-100%). Response via AVRCP_SUBEVENT_SET_ABSOLUTE_VOLUME_RESPONSE
331   * @param avrcp_cid
332   * @return status
333   */
334  uint8_t avrcp_controller_set_absolute_volume(uint16_t avrcp_cid, uint8_t volume);
335  
336  
337  /**
338   * @brief Skip to next playing media. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
339   * @param avrcp_cid
340   * @return status
341   */
342  uint8_t avrcp_controller_skip(uint16_t avrcp_cid);
343  
344  uint8_t avrcp_controller_query_player_application_setting_attributes(uint16_t avrcp_cid);
345  uint8_t avrcp_controller_query_player_application_setting_values(uint16_t avrcp_cid, avrcp_player_application_setting_attribute_id_t attribute_id);
346  
347  uint8_t avrcp_controller_query_player_application_setting_attribute_text(uint16_t avrcp_cid);
348  uint8_t avrcp_controller_query_player_application_setting_value_text(uint16_t avrcp_cid);
349  
350  uint8_t avrcp_controller_inform_displayable_characterset(uint16_t avrcp_cid, uint8_t character_set_num, uint16_t * character_set);
351  uint8_t avrcp_controller_inform_battery_status(uint16_t avrcp_cid, avrcp_battery_status_t battery_status);
352  
353  /**
354   * @brief Query repeat and shuffle mode. Response via AVRCP_SUBEVENT_SHUFFLE_AND_REPEAT_MODE.
355   * @param avrcp_cid
356   * @return status
357   */
358  uint8_t avrcp_controller_query_shuffle_and_repeat_modes(uint16_t avrcp_cid);
359  
360  /**
361   * @brief Set shuffle mode. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
362   * @param avrcp_cid
363   * @return status
364   */
365  uint8_t avrcp_controller_set_shuffle_mode(uint16_t avrcp_cid, avrcp_shuffle_mode_t mode);
366  
367  /**
368   * @brief Set repeat mode. Event AVRCP_SUBEVENT_OPERATION_COMPLETE returns operation id and status.
369   * @param avrcp_cid
370   * @return status
371   */
372  uint8_t avrcp_controller_set_repeat_mode(uint16_t avrcp_cid, avrcp_repeat_mode_t mode);
373  
374  /**
375   * @brief The PlayItem command starts playing an item indicated by the UID. It is routed to the Addressed Player.
376   * @param avrcp_cid
377   * @param uid
378   * @param uid_counter
379   * @param scope
380   **/
381  uint8_t avrcp_controller_play_item_for_scope(uint16_t avrcp_cid, uint8_t * uid, uint16_t uid_counter, avrcp_browsing_scope_t scope);
382  
383  /**
384   * @brief Adds an item indicated by the UID to the Now Playing queue.
385   * @param avrcp_cid
386   * @param uid
387   * @param uid_counter
388   * @param scope
389   **/
390  uint8_t avrcp_controller_add_item_from_scope_to_now_playing_list(uint16_t avrcp_cid, uint8_t * uid, uint16_t uid_counter, avrcp_browsing_scope_t scope);
391  
392  /**
393   * @brief Set addressed player.
394   * @param avrcp_cid
395   * @param addressed_player_id
396   */
397  uint8_t avrcp_controller_set_addressed_player(uint16_t avrcp_cid, uint16_t addressed_player_id);
398  
399  /**
400   * @brief Send custom command
401   * @param avrcp_cid
402   * @param command_type
403   * @param subunit_type
404   * @param subunit_id
405   * @param pdu_id
406   * @param company_id
407   * @param data
408   * @param data_len
409   */
410  uint8_t avrcp_controller_send_custom_command(uint16_t avrcp_cid,
411      avrcp_command_type_t command_type,
412      avrcp_subunit_type_t subunit_type, avrcp_subunit_id_t subunit_id,
413      avrcp_pdu_id_t pdu_id, uint32_t company_id,
414      const uint8_t * data, uint16_t data_len);
415  
416  /**
417   * @brief De-Init AVRCP Controller
418   */
419  void avrcp_controller_deinit(void);
420  
421  /* API_END */
422  
423  // send press command if connection is open. use with great care and only if there's no other option
424  uint8_t avrcp_controller_force_send_press_cmd(uint16_t avrcp_cid, avrcp_operation_id_t operation_id);
425  
426  // Used by AVRCP controller and AVRCP browsing controller
427  extern avrcp_context_t avrcp_controller_context;
428  
429  #if defined __cplusplus
430  }
431  #endif
432  
433  #endif // AVRCP_CONTROLLER_H
434