-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtusbaudioapi.h
2493 lines (1753 loc) · 79.3 KB
/
tusbaudioapi.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
Thesycon® Systemsoftware & Consulting GmbH
TUSBAudio
USB Audio 2.0 Class Driver for Windows
Reference Manual
Version: 1.22.0
Date: 02 December 2010
Authors: Udo Eberhardt
Frank Senf
Thesycon Systemsoftware & Consulting GmbH
Werner-von-Siemens-Str. 2
D-98693 Ilmenau
Germany
Tel: +49 3677 8462 0
Fax: +49 3677 8462 18
http://www.thesycon.de
*/
/*tusbaudioapi.dll loads configuration information from custom.ini which must be present in the
same directory as the DLL itself. */
#include <wchar.h> //added by MB
typedef unsigned int TUsbAudioStatus; //added by MB
typedef unsigned long* WCHAR; added by MB
#define TUSBAUDIO_MAX_STRDESC_STRLEN 200 //?? SIZE
/*TUsbAudioDeviceProperties
This structure provides static information associated with a USB audio device.
Definition */
typedef struct /*tagTUsbAudioDeviceProperties*/{
unsigned int usbVendorId;
unsigned int usbProductId;
unsigned int usbRevisionId;
WCHAR serialNumberString[TUSBAUDIO_MAX_STRDESC_STRLEN]; //UTF-32 or UTF-16??
WCHAR manufacturerString[TUSBAUDIO_MAX_STRDESC_STRLEN];
WCHAR productString[TUSBAUDIO_MAX_STRDESC_STRLEN];
unsigned int flags;
} TUsbAudioDeviceProperties;
/*Members
usbVendorId
Specifies the USB vendor ID (VID) as reported by the device in the USB device descriptor.
usbProductId
Specifies the USB product ID (PID) as reported by the device in the USB device descriptor.
usbRevisionId
Specifies the revision code (bcdDevice) as reported by the device in the USB device descriptor.
serialNumberString[TUSBAUDIO_MAX_STRDESC_STRLEN]
Contains the serial number string as reported by the device per string descriptor. If the device
does not support a USB serial number then the string contains a device instance ID generated
internally by Windows. This field contains a sequence of UNICODE characters which is
guaranteed to be terminated by a UNICODE null character.
manufacturerString[TUSBAUDIO_MAX_STRDESC_STRLEN]
Contains the Manufacturer string as reported by the device per string descriptor. If the device
does not support a Manufacturer string then this field is set to an empty string. This field
contains a sequence of UNICODE characters which is guaranteed to be terminated by a
UNICODE null character.
productString[TUSBAUDIO_MAX_STRDESC_STRLEN]
Contains the Product string as reported by the device per string descriptor. If the device does
not support a Product string then this field is set to an empty string. This field contains a
sequence of UNICODE characters which is guaranteed to be terminated by a UNICODE null
character.
flags
Contains a set of flags as a bitwise-or combination of the following constants.
TUSBAUDIO_DEVPROP_FLAG_HIGH_SPEED_SUPPORTED
If this flag is set then the device is capable of USB high-speed mode. If this flag is clear
then the device supports USB full-speed mode only.
TUSBAUDIO_DEVPROP_FLAG_HIGH_SPEED
If this flag is set then the device is currently connected to a high-speed USB port and works
in high-speed mode. If this flag is clear then the device is currently connected to a USB
port which supports full-speed mode only.
TUSBAUDIO_DEVPROP_FLAG_DFU_SUPPORTED
If this flag is set then the device supports device firmware upgrade (DFU).
TUSBAUDIO_DEVPROP_FLAG_DSP_PLUGIN_PRESENT
If this flag is set then a DSP plugin is loaded for the device.
TUSBAUDIO_DEVPROP_FLAG_AUDIOCLASS10_SUPPORTED
If this flag is set the device complies to USB Audio Class 1.0.
TUSBAUDIO_DEVPROP_FLAG_AUDIOCLASS20_SUPPORTED
If this flag is set the device complies to USB Audio Class 2.0.
Comments
An application can use the USB VID, PID and serial number information provided by this
struct to unambiguously identify a particular device instance.
See Also
TUSBAUDIO_GetDeviceProperties (page 18) */
/*TUsbAudioClockSource
This structure provides detailed information on a specific Clock Source of the USB Audio
Function.
Definition */
typedef struct /*tagTUsbAudioClockSource*/{
unsigned int clockSourceId;
unsigned int clockSourceUnitId;
unsigned int clockSelectorPinNumber;
unsigned int clockIsValid;
unsigned int sampleRate;
WCHAR clockNameString[TUSBAUDIO_MAX_STRDESC_STRLEN];
} TUsbAudioClockSource;
/*Members
clockSourceId
Contains the unique ID that unambiguously identifies the clock source at the driver API.
The ID values are driver-defined. An application must not interpret the value.
clockSourceUnitId
Contains the unit ID of the Clock Source entity within the audio function.
clockSelectorPinNumber
Contains the zero-based index of the clock selector input pin where the clock selector is
connected.
clockIsValid
Specifies the current state of the clock source (validity).
This member will be set to 1 of the clock is stable or to zero otherwise.
sampleRate
Current sample rate of the clock source, in samples per second.
This member is only valid of clockIsValidis set to 1.
clockNameString[TUSBAUDIO_MAX_STRDESC_STRLEN]
Zero-terminated wide character string that describes the clock source (taken from USB string
descriptor).
See Also
TUSBAUDIO_GetSupportedClockSources (page 25)
TUSBAUDIO_GetCurrentClockSource (page 26)
TUSBAUDIO_SetCurrentClockSource (page 27) */
/*TUsbAudioStreamFormat
This structure provides information on a specific stream format supported by the device.
Definition */
typedef struct /*tagTUsbAudioStreamFormat*/{
unsigned int formatId;
unsigned int bitsPerSample;
unsigned int numberOfChannels;
WCHAR formatNameString[TUSBAUDIO_MAX_STRDESC_STRLEN];
} TUsbAudioStreamFormat;
/*Members
formatId
Contains the unique ID that unambiguously identifies the stream format at the driver API.
The ID values are driver-defined. An application must not interpret the value.
bitsPerSample
Contains the number of valid bits per sample (16 or 24).
numberOfChannels
Contains the number of audio channels covered by the stream format.
formatNameString[TUSBAUDIO_MAX_STRDESC_STRLEN]
Zero-terminated wide character string that describes the stream format (taken from USB string
descriptor).
See Also
TUSBAUDIO_GetSupportedStreamFormats (page 28)
TUSBAUDIO_GetCurrentStreamFormat (page 30)
TUSBAUDIO_SetCurrentStreamFormat (page 31) */
/*TUsbAudioChannelProperty
This structure provides information on a specific audio channel of the device.
Definition */
typedef struct /*tagTUsbAudioChannelProperty*/{
unsigned int channelIndex;
unsigned int isInput;
unsigned int flags;
unsigned char featureUnitId;
unsigned char featureUnitLogicalChannel;
short volumeRangeMin;
short volumeRangeMax;
unsigned short volumeRangeStep;
WCHAR channelNameString[TUSBAUDIO_MAX_STRDESC_STRLEN];
} TUsbAudioChannelProperty;
/*Members
channelIndex
Contains the zero-based index of the channel within the associated stream.
isInput
Contains the channel direction. This member is set to one for input (record) channels and to
zero for output (playback) channels.
flags
Contains a set of flags as a bitwise-or combination of the following constants.
TUSBAUDIO_CHANPROP_FLAG_VOLUME_MAPPED
If this flag is set then the Windows Audio volume control for the channel is mapped to the
feature unit specified in featureUnitId.
TUSBAUDIO_CHANPROP_FLAG_MUTE_MAPPED
If this flag is set then the Windows Audio mute control for the channel is mapped to the
feature unit specified in featureUnitId.
featureUnitId
Contains the ID of the feature unit within the audio function that is used by Windows Audio to
control volume and/or mute of the channel.
This ID has to be used as entityIDwhen calling the private API to send volume or mute
control requests for this channel to the device.
The ID is valid only if one of TUSBAUDIO_CHANPROP_FLAG_VOLUME_MAPPEDor
TUSBAUDIO_CHANPROP_FLAG_MUTE_MAPPEDis set in the flagsmember.
featureUnitLogicalChannel
Contains the logical channel number within the feature unit that corresponds with the channel.
This number has to be used as channelOrMixerControlwhen calling the private API to
send volume or mute control requests for this channel to the device.
volumeRangeMin
Contains the minimum volume value that is supported by the channel.
This field is only valid if TUSBAUDIO_CHANPROP_FLAG_VOLUME_MAPPEDis set in the
flagsmember.
volumeRangeMax
Contains the maximum volume value that is supported by the channel.
This field is only valid if TUSBAUDIO_CHANPROP_FLAG_VOLUME_MAPPEDis set in the
flagsmember.
volumeRangeStep
Contains the step size for volume values supported for the channel.
This field is only valid if TUSBAUDIO_CHANPROP_FLAG_VOLUME_MAPPEDis set in the
flagsmember.
channelNameString[TUSBAUDIO_MAX_STRDESC_STRLEN]
Zero-terminated wide character string that describes the channel. The channel name is taken
from the USB string descriptor if available or generated internally otherwise.
Comments
The values that are returned in volumeRangeMin, volumeRangeMaxand
volumeRangeStepare in the range as defined by the USB Audio Class specification
(-127.9961 decibels to +127.9961 decibels in 1/256 decibel steps).
See Also
TUSBAUDIO_GetChannelProperties (page 32)
TUSBAUDIO_AudioControlRequestGet (page 37)
TUSBAUDIO_AudioControlRequestSet (page 35) */
/*TUsbAudioNotifyEvent
This enumeration type defines constants that identify notification event messages issued by the
device or the driver.
Definition */
typedef enum tagTUsbAudioNotifyEvent{
NotifyEvent_SampleRateChanged,
NotifyEvent_StreamFormatChanged,
NotifyEvent_AcNodeInterrupt,
NotifyEvent_VolumeChanged,
NotifyEvent_MuteChanged
} TUsbAudioNotifyEvent;
/*Entries
NotifyEvent_SampleRateChanged
This event message is issued by the driver when the sample rate changes. This event belongs
to the TUSBAUDIO_NOTIFY_CATEGORY_SAMPLE_RATE_CHANGEcategory.
Data field: No data field is attached to this type of event.
NotifyEvent_StreamFormatChanged
This event message is issued by the driver when the stream format changes. This event
belongs to the TUSBAUDIO_NOTIFY_CATEGORY_STREAM_CHANGEcategory.
Data field: No data field is attached to this type of event.
NotifyEvent_AcNodeInterrupt
This event message is issued by an audio control node (unit) of the device. This event belongs
to the TUSBAUDIO_NOTIFY_CATEGORY_AC_NODE_INTERRUPTcategory.
Data field: The data field attached to this event contains the interrupt data message defined by
the USB audio class 2.0 specification. The size of this message is 6 bytes. The data layout is
defined by the USB audio class 2.0 specification. See also the
T_UsbClsAudio20_AC_InterruptDataMessagestruct type defined in
tusb_cls_audio20.h.
NotifyEvent_VolumeChanged
This event message is issued by the driver if the volume of a specific channel is changed
through the Windows mixer API. For example, this happens if a user modifies volume in the
standard windows sound panel. This event belongs to the
TUSBAUDIO_NOTIFY_CATEGORY_VOLUME_CHANGEcategory.
Data field: The data field attached to this event contains a TUsbAudioNotifyVolumeChange
structure.
NotifyEvent_MuteChanged
This event message is issued by the driver if the mute state of a specific channel is changed
through the Windows mixer API. For example, this happens if a user modifies mute in the
standard windows sound panel. This event belongs to the
TUSBAUDIO_NOTIFY_CATEGORY_VOLUME_CHANGEcategory.
Data field: The data field attached to this event contains a TUsbAudioNotifyVolumeChange
structure.
Comments
An application can filter event messages to be received by means of event categories.
Categories are defined by TUSBAUDIO_NOTIFY_CATEGORY_xxxconstants. See
TUSBAUDIO_RegisterDeviceNotification for more information.
See Also
TUSBAUDIO_RegisterDeviceNotification (page 19)
TUSBAUDIO_ReadDeviceNotification (page 21)
TUsbAudioNotifyVolumeChange (page 66) */
/*TUsbAudioDfuProcState
This enumeration type defines constants that indicate the current state of the DFU operation.
Definition */
typedef enum tagTUsbAudioDfuProcState{
DfuProcState_Idle,
DfuProcState_Initializing,
DfuProcState_EnteringDfuMode,
DfuProcState_InProgress,
DfuProcState_EnteringAppMode,
DfuProcState_Finished,
DfuProcState_Failed
} TUsbAudioDfuProcState;
/*Entries
DfuProcState_Idle
No DFU operation is in progress.
DfuProcState_Initializing
The DFU operation is about to start.
DfuProcState_EnteringDfuMode
The device is entering DFU mode (DFU firmware is about to be started).
DfuProcState_InProgress
The DFU operation is in progress.
DfuProcState_EnteringAppMode
The device is entering APP mode (application is about to be started).
DfuProcState_Finished
The DFU operation has completed successfully.
DfuProcState_Failed
The DFU operation has completed with error.
Comments
An application calls TUSBAUDIO_GetDfuStatus to query the current state of the DFU
operation.
See Also
TUSBAUDIO_GetDfuStatus (page 61) */
/*TUsbAudioDeviceRunMode
This enumeration type defines constants that indicate the firmware that is currently running on
the device.
Definition */
typedef enum tagTUsbAudioDeviceRunMode{
DeviceRunMode_APP,
DeviceRunMode_DFU
} TUsbAudioDeviceRunMode;
/*Entries
DeviceRunMode_APP
The application firmware is running (APP mode).
DeviceRunMode_DFU
The DFU firmware is running (DFU mode).
Comments
An application calls TUSBAUDIO_GetDeviceUsbMode to query the firmware that is
running on the device.
See Also
TUSBAUDIO_GetDeviceUsbMode (page 48) */
/*----------------- Functions --------------------------------------*/
/*TUSBAUDIO_GetApiVersion
This function returns the current version number of the application programming interface (API)
exported by the DLL.
Definition
*/
unsigned int
TUSBAUDIO_GetApiVersion();
/* Return Value
The function returns the TUSBAUDIO_API_VERSIONconstant the DLL was compiled with.
The high-order 16 bits contain the major version number, the low-order 16 bits contain the
minor version number.
Comments
Regarding the API version of the DLL the following convention is defined: If changes are
made to the programming interface that are compatible with previous versions (e.g. a new
function is added) then the minor version number will be incremented. If changes are made
that cause an incompatibility with previous versions of the interface then the major version
number will be incremented.
Applications should call TUSBAUDIO_CheckApiVersion to check if the DLL’s API is
compatible with the version of the header file the application was compiled with.
----------------------------------------------------------------------------------------
TUSBAUDIO_CheckApiVersion
This function checks if the application programming interface of the DLL is compatible with the
version the application was compiled with.
Definition
*/
int
TUSBAUDIO_CheckApiVersion(
unsigned long majorVersion,
unsigned long minorVersion
);
/* Parameters
majorVersion
Specifies the major API version that the application expects. Callers should set this parameter
to the TUSBAUDIO_API_VERSION_MJconstant.
minorVersion
Specifies the minor API version that the application expects. Callers should set this parameter
to the TUSBAUDIO_API_VERSION_MNconstant.
Return Value
The function returns 1if the DLL is compatible with the caller. The function returns 0if the
version does not match and the calling application is incompatible with the DLL.
Comments
Regarding the API version of the DLL the following convention is defined: If changes are
made to the programming interface that are compatible with previous versions (e.g. a new
function is added) then the minor version number will be incremented. If changes are made
that cause an incompatibility with previous versions of the interface then the major version
number will be incremented.
Applications should call this function to check if the DLL’s API is compatible with the version
of the header file the application was compiled with.
The function succeeds if the major version of the DLL is equal to the expected major version
and if the minor version of the DLL is greater than or equal to the expected minor version.
See Also
TUSBAUDIO_GetApiVersion (page 8)
---------------------------------------------------------------------
TUSBAUDIO_RegisterPnpNotification
Register with the driver to receive notifications when devices are plugged or unplugged.
Definition
*/
TUsbAudioStatus
TUSBAUDIO_RegisterPnpNotification(
HANDLE deviceArrivalEvent,
HANDLE deviceRemovedEvent,
void* windowHandle,
unsigned int windowMsgCode,
unsigned int flags
);
/* Parameters
deviceArrivalEvent
Handle to a user-created Win32 event object that will be signaled by the driver when a new
device is connected to the system. This parameter is optional and can be set to NULL if no
event object is to be registered.
deviceRemovedEvent
Handle to a user-created Win32 event object that will be signaled by the driver when a device
is disconnected from the system. This parameter is optional and can be set to NULL if no
event object is to be registered.
windowHandle
Handle (HWND) that identifies a window in the user’s application. The driver posts a message
to this window when a device is connected or disconnected. For more information, see the
Comments section below.
This parameter is optional and can be set to NULL. The driver will not post a window
message in this case.
windowMsgCode
User-defined message code that identifies the window message posted by the driver. An
application should use a numeric code that is greater than WM_USER, for example
(WM_USER + 100).
This parameter will be ignored if windowHandleis set to NULL.
flags
This parameter is reserved for future use and should be set to zero.
Return Value
If the operation was successful the function returns TSTATUS_SUCCESS. If the operation
failed the function returns one of the TSTATUS_xxxstatus codes.
Comments
Depending on the application type an application can implement two different approaches as
discussed in the following.
Event object based notification:
The application creates event objects using the Win32 call CreateEvent and then passes the
handles returned by Windows to TUSBAUDIO_RegisterPnpNotification. The
argument windowHandleis set to NULL in this case. Typically the application uses a
dedicated thread to wait on the event objects, e.g. by using the Win32 call
WaitForMultipleObjects. The thread gets triggered when one of the events is signalled by the
driver. The driver just calls SetEvent with the provided handle. It is up to application designer
to decide which type of event object (auto-reset or manual-reset) is to be used.
Window message based notification:
The application defines a private window message code. e.g. set to (WM_USER + 100), and
passes this code to TUSBAUDIO_RegisterPnpNotificationas windowMsgCode
argument. The arguments deviceArrivalEventand deviceRemovedEventare both
set to NULL in this case. The application also passes a window handle (typically the main
window handle) as windowHandleargument. In case a device plug or unplug event occurs,
the driver posts the specified message to the specified window using the Win32 call
PostMessage. If a new device is connected (plugged in) the wParamparameter of the
message will be set to TUSBAUDIO_DEVICE_ARRIVAL_MSG. If a device is disconnected
(unplugged) the wParamparameter of the message will be set to
TUSBAUDIO_DEVICE_REMOVED_MSG.
See Also
TUSBAUDIO_UnregisterPnpNotification (page 12)
TUSBAUDIO_UnregisterPnpNotification
Remove any plug/unplug event registration previously created by a call to
TUSBAUDIO_RegisterPnpNotification.
Definition
*/
void
TUSBAUDIO_UnregisterPnpNotification();
/*Comments
An application must call this function before it destroys any objects previously passed to
TUSBAUDIO_RegisterPnpNotification. It is safe to call this function if no registration
currently exists. The function performs no operation in this case.
See Also
TUSBAUDIO_RegisterPnpNotification (page 10)
------------------------------------------------------------------------------
TUSBAUDIO_EnumerateDevices
Enumerate the USB audio devices available in the system that may be controlled by the DLL.
Definition
*/
TUsbAudioStatus
TUSBAUDIO_EnumerateDevices();
/*Return Value
If the operation was successful the function returns TSTATUS_SUCCESS. If the operation
failed the function returns one of the TSTATUS_xxxstatus codes.
Comments
This function needs to be called once before a device instance can be opened via
TUSBAUDIO_OpenDeviceByIndex.
A successful call to this function creates an internal device list which represents all supported
USB audio devices available in the system. Device instances (USB devices) are addressed by
means of a zero-based index that is passed to TUSBAUDIO_OpenDeviceByIndex.
Even if the function succeeds, there may be no devices available in the system. An application
should call TUSBAUDIO_GetDeviceCount to check for available devices.
A call to this function invalidates all open device instance handles. All current handles must
be closed via TUSBAUDIO_CloseDevice before this function is called. After this function is
called, handles can be opened again by calling TUSBAUDIO_OpenDeviceByIndex.
See Also
TUSBAUDIO_OpenDeviceByIndex (page 15)
TUSBAUDIO_CloseDevice (page 17)
TUSBAUDIO_GetDeviceCount (page 14)
/**************************************************************************/
/* TUSBAUDIO_GetDeviceCount
Query the number of USB audio devices available in the system that may be controlled by the
DLL.
Definition
*/
unsigned int
TUSBAUDIO_GetDeviceCount();
/*Return Value
The function returns the number of supported USB audio devices.
Comments
Supported USB audio devices are enumerated by calling TUSBAUDIO_EnumerateDevices.
Even if the TUSBAUDIO_EnumerateDevices function succeeds, there may be no devices
available in the system. An application should query the device count to check for available
devices.
See Also
TUSBAUDIO_EnumerateDevices (page 13)
/**************************************************************************/
/* TUSBAUDIO_OpenDeviceByIndex
Open a device instance (USB audio device).
Definition
*/
TUsbAudioStatus
TUSBAUDIO_OpenDeviceByIndex(
unsigned int deviceIndex,
TUsbAudioHandle* deviceHandle
);
/*Parameters
deviceIndex
Zero-based index that specifies the device instance to be opened. Device instances count from
zero to deviceCount-1. The deviceCountvalue is returned by
TUSBAUDIO_GetDeviceCount.
deviceHandle
Address of a caller-provided variable that will be set to the device instance handle if the
function succeeds. If the function fails deviceHandlewill be set to NULL which is an
invalid handle value.
Return Value
If the operation was successful the function returns TSTATUS_SUCCESS. If the operation
failed the function returns one of the TSTATUS_xxxstatus codes.
TSTATUS_ENUM_REQUIREDis returned if TUSBAUDIO_EnumerateDevices was not yet
called.
Comments
A device instance opened by this function corresponds to a USB audio device.
TUSBAUDIO_EnumerateDevices needs to be called before any device instance can be
opened.
Each device index value corresponds to a physical device instance (USB audio device) present
in the system. The device index that is associated with a particular device may change by a
call to TUSBAUDIO_EnumerateDevices and must not be used to identify a device. An
application can query device identification information by calling
TUSBAUDIO_GetDeviceProperties.
See Also
TUSBAUDIO_GetDeviceCount (page 14)
TUSBAUDIO_EnumerateDevices (page 13)
TUSBAUDIO_GetDeviceProperties (page 18)
TUSBAUDIO_CloseDevice (page 17) */
/*TUSBAUDIO_CloseDevice
Close the specified device instance.
Definition */
TUsbAudioStatus
TUSBAUDIO_CloseDevice(
TUsbAudioHandle deviceHandle
);
/*Parameter
deviceHandle
Handle that identifies the device instance (USB audio device). The handle needs to be created
by a call to TUSBAUDIO_OpenDeviceByIndex.
Return Value
If the operation was successful the function returns TSTATUS_SUCCESS. If the operation
failed the function returns one of the TSTATUS_xxxstatus codes.
TSTATUS_INVALD_HANDLEis returned if the given deviceHandleis invalid.
Comments
Important: The specified device handle becomes invalid after this call and must not be used
in any subsequent function call.
See Also
TUSBAUDIO_OpenDeviceByIndex (page 15)
*/
/*TUSBAUDIO_GetDeviceProperties
Query USB IDs and properties for a specific device.
Definition*/
// TUsbAudioStatus
// TUSBAUDIO_GetDeviceProperties(
// TUsbAudioHandle deviceHandle,
// TUsbAudioDeviceProperties* properties
// );
/*Parameters
deviceHandle
Handle that identifies the device instance (USB audio device). The handle needs to be created
by a call to TUSBAUDIO_OpenDeviceByIndex.
properties
Points to a caller provided struct of type TUsbAudioDeviceProperties that receives the
requested information.
Return Value
If the operation was successful the function returns TSTATUS_SUCCESS. If the operation
failed the function returns one of the TSTATUS_xxxstatus codes.
Comments
This function reports static information associated with the specified device. This includes
USB vendor and product IDs, serial number, etc. See TUsbAudioDeviceProperties for more
information.
See Also
TUSBAUDIO_OpenDeviceByIndex (page 15)
TUsbAudioDeviceProperties (page 69) */
/*TUSBAUDIO_RegisterDeviceNotification
Register for notifications to be issued by the driver on device state changes.
Definition */
TUsbAudioStatus
TUSBAUDIO_RegisterDeviceNotification(
TUsbAudioHandle deviceHandle,
unsigned int categoryFilter,
HANDLE sharedEvent,
unsigned int flags
);
/*Parameters
deviceHandle
Handle that identifies the device instance (USB audio device). The handle needs to be created
by a call to TUSBAUDIO_OpenDeviceByIndex.
categoryFilter
Specifies the class of events to be received as a bitwise OR combination of bit flags.
TUSBAUDIO_NOTIFY_CATEGORY_NONE
No event will be posted. Use this to unregister with the driver.
TUSBAUDIO_NOTIFY_CATEGORY_ALL
All kind of events will be posted.
TUSBAUDIO_NOTIFY_CATEGORY_SAMPLE_RATE_CHANGE
Device sample rate changed events will be posted. See TUsbAudioNotifyEvent for more
information.
TUSBAUDIO_NOTIFY_CATEGORY_STREAM_CHANGE
Device stream format changed events will be posted. See TUsbAudioNotifyEvent for
more information.
TUSBAUDIO_NOTIFY_CATEGORY_VOLUME_CHANGE
Volume or Mute changed events will be posted. See TUsbAudioNotifyEvent for more
information.
TUSBAUDIO_NOTIFY_CATEGORY_AC_NODE_INTERRUPT
Audio control node events will be posted. See TUsbAudioNotifyEvent for more
information.
sharedEvent
Refers to a Win32 event object created by the caller. The driver will set this event to signaled
state if event messages are available and can be retrieved through
TUSBAUDIO_ReadDeviceNotification. The driver will reset this event to not-signaled state
if no event messages are available. The event shared with the driver should be of auto-reset
type.
This parameter is optional. If an application does not need to share an event with the driver, it
passes NULL.
flags
This parameter is reserved for future use and should be set to zero.
Return Value
If the operation was successful the function returns TSTATUS_SUCCESS. If the operation
failed the function returns one of the TSTATUS_xxxstatus codes.
Comments
A call to this function with categoryFilter !=
TUSBAUDIO_NOTIFY_CATEGORY_NONEwill enable delivery of notification event
messages in the driver.
To stop receiving event messages, an application can unregister with the driver by calling this
function with categoryFilterset to TUSBAUDIO_NOTIFY_CATEGORY_NONEand
sharedEventset to NULL.
If an application shares an event object with the driver then on every state change of the
driver-internal event queue the driver updates the state of this event object to reflect the current
state of the queue. The driver will signal the event object if the queue is not empty. The driver
will clear the event object if the queue is empty.
In order to guarantee correct functionality, an application should use an auto-reset type event
object. Typically, an application uses the shared event object to trigger an internal worker
thread. Once this thread awakes the event object will be automatically reset (auto-reset
behavior).
The application uses TUSBAUDIO_ReadDeviceNotification to retrieve a message from the
driver-internal queue. Each call to TUSBAUDIO_ReadDeviceNotification causes the driver
to update the state of the shared event.
If the application shares a manual-reset type event and needs to clear the event manually then
it must clear the event before it calls TUSBAUDIO_ReadDeviceNotification.
See Also
TUSBAUDIO_ReadDeviceNotification (page 21)
TUSBAUDIO_OpenDeviceByIndex (page 15)
TUsbAudioNotifyEvent (page 75)
*/
/*TUSBAUDIO_ReadDeviceNotification
Retrieve an event message from the driver-internal queue.
Definition */
TUsbAudioStatus
TUSBAUDIO_ReadDeviceNotification(
TUsbAudioHandle deviceHandle,
TUsbAudioNotifyEvent* eventType,
unsigned char* dataBuffer,
unsigned int dataBufferSize,
unsigned int* dataBytesReturned
);
/*Parameters
deviceHandle
Handle that identifies the device instance (USB audio device). The handle needs to be created
by a call to TUSBAUDIO_OpenDeviceByIndex.
eventType
Points to a caller-provided variable that will receive the type of the event. See
TUsbAudioNotifyEvent for more information.
dataBuffer
Points to a caller-provided buffer that will receive additional data that may be attached to the
event. An application should provide a buffer of at least
TUSBAUDIO_NOTIFY_EVENT_MAX_DATA_BYTESbytes in size. See also the Comments
section below.
dataBufferSize
Specifies the size, in bytes, of the buffer pointed to by dataBuffer. An application should
provide a buffer of at least TUSBAUDIO_NOTIFY_EVENT_MAX_DATA_BYTESbytes in
size. See also the Comments section below.
dataBytesReturned
Points to a caller-provided variable that will be set to the number of bytes returned in the
buffer pointed to by dataBuffer. This variable is optional. An application can set
dataBytesReturnedto NULL if the information is not needed.
Return Value
If the operation was successful the function returns TSTATUS_SUCCESS. The event message
has been removed from the driver-internal queue in this case.
The function returns TSTATUS_NO_MORE_ITEMSif the driver-internal event message
queue is empty. No event message has been returned in this case.
The function returns TSTATUS_BUFFER_TOO_SMALLif the buffer provided at
dataBufferis too small to receive the data field attached to the event message. The current
event message has not been removed from the driver-internal queue in this case. The
application needs to call this function again providing a larger buffer.
Comments
An application calls this function to retrieve an event message from the driver-internal event
message queue. To receive messages, an application needs to register for notifications via
TUSBAUDIO_RegisterDeviceNotification.
If the application registered a shared event object with the driver, the driver will update that
event’s state on every call to this function. Fore more information on how to register an event
object, see also TUSBAUDIO_RegisterDeviceNotification.
Some types of messages have an attached data field. See TUsbAudioNotifyEvent for more
information. To reveive this data field (if present), an application should provide a data buffer
with each call to this function. The buffer must be at least
TUSBAUDIO_NOTIFY_EVENT_MAX_DATA_BYTESbytes in size.
See Also
TUSBAUDIO_RegisterDeviceNotification (page 19)
TUSBAUDIO_OpenDeviceByIndex (page 15)
TUsbAudioNotifyEvent (page 75) */
/*TUSBAUDIO_GetSupportedSampleRates
Query the list of sampling rates that are supported by a specific device.
Definition */
TUsbAudioStatus
TUSBAUDIO_GetSupportedSampleRates(
TUsbAudioHandle deviceHandle,
unsigned int sampleRateMaxCount,
unsigned int sampleRateArray[],
unsigned int* sampleRateCount
);
/*Parameters
deviceHandle
Handle that identifies the device instance (USB audio device). The handle needs to be created
by a call to TUSBAUDIO_OpenDeviceByIndex.
sampleRateMaxCount
Specifies the maximum number of sampling rates that can be stored to sampleRateArray.
sampleRateArray[]
Caller-provided buffer that will receive the supported sampling rates. The sampling rates are
specified in 1/s.
sampleRateCount
Caller-provided variable that will be set to the number of valid entries in
sampleRateArrayon return.
Return Value
If the operation was successful the function returns TSTATUS_SUCCESS. If the operation
failed the function returns one of the TSTATUS_xxxstatus codes.
See Also
TUSBAUDIO_GetCurrentSampleRate (page 24)*/
/*TUSBAUDIO_GetCurrentSampleRate
Query the sampling rate that is currently set for a specific device.
Definition */
TUsbAudioStatus
TUSBAUDIO_GetCurrentSampleRate(
TUsbAudioHandle deviceHandle,
unsigned int* sampleRate
);
/*Parameters
deviceHandle
Handle that identifies the device instance (USB audio device). The handle needs to be created
by a call to TUSBAUDIO_OpenDeviceByIndex.
sampleRate
Caller-provided variable that will be set to the current sampling rate. The sampling rate is
specified in 1/s.
Return Value
If the operation was successful the function returns TSTATUS_SUCCESS. If the operation
failed the function returns one of the TSTATUS_xxxstatus codes.