SGGetChannelDeviceList(IM: QC)

Inside Macintosh: QuickTime Components /

Chapter 5 - Sequence Grabber Components / Sequence Grabber Components Reference

Sequence Grabber Component Functions / Working With Channel Devices

SGGetChannelDeviceList
The SGGetChannelDeviceList function allows you to retrieve a list of the devices that are valid for a specified channel.
pascal ComponentResult SGGetChannelDeviceList (SGChannel c, 
                                             long selectionFlags, 
                                             SGDeviceList *list);
c
Identifies the channel for this operation. You provide your
connection identifier. You connect to a channel component by calling the SGNewChannel or SGNewChannelFromComponent function, discussed on page 5-29 and page 5-30, respectively.
selectionFlags

Controls the data returned for each device. The following flags are defined:
sgDeviceListWithIcons
Specifies whether you want to retrieve an icon for each device. If you set this flag to 1, the sequence grabber returns an icon for each device in the list, in the icon field. If you set this flag to 0, the sequence grabber sets the icon fields to 0.
sgDeviceListDontCheckAvailability
Controls whether the sequence grabber verifies
that each device is currently available. If you set this
flag to 1, the sequence grabber does not check the availability of each device. Otherwise, the sequence grabber checks each device's availability, and sets the sgDeviceNameFlagDeviceUnavailable flag appropriately in each device name structure that is returned.

Note that checking device availability slows this function. In general, however, you should check availability if you plan to present a list of devices to the user. Otherwise, the user may select a device that is unavailable.
list
Defines a pointer to a device list structure pointer. The sequence grabber creates a device name structure and returns a pointer to that structure in the field referred to by this parameter. When you are done with the list, use the SGDisposeDeviceList function (described in the next section) to dispose of the memory used by the list.

DESCRIPTION
This function allows you to retrieve a list of the devices that may be used with a channel. Each entry in this list identifies a valid device by name. Your application may then place these device names into a menu using the SGAppendDeviceListToMenu function, which is described on page 5-72.
This function can be useful for retrieving the name of the current device. Retrieve the device list and use the selectedIndex field to determine which device is currently
in use.

RESULT CODES
Memory Manager errors

SEE ALSO
When you are done with the list, use the SGDisposeDeviceList function to dispose of the memory used by the list. This function is discussed next.