alOpenPort(3dm)                                                alOpenPort(3dm)


NAME
     alOpenPort - open an audio port

SYNOPSIS
     #include <dmedia/audio.h>

     ALport alOpenPort(char *name, char *direction, ALconfig config)

PARAMETER
     name        A port name is a character string describing the port.  It is
                 intended for human consumption, similar to a window title.
                 Port names have a maximum length of 20 characters.

     direction   Specifies whether the port is for input or output.

                 "r" specifies an input port.

                 "w" specifies an output port.

     config      Expects an ALconfig, as returned by alNewConfig(3dm) or
                 alGetConfig(3dm).  This structure describes the data format
                 and queue size for the port.

                 Passing a null (0) value for config yields a port with the
                 default configuration.

DESCRIPTION
     audio port is the mechanism through which an application reads or writes
     real-time audio data.  There are two types of ports: input and output. An
     input port receives a real-time stream of audio data from an audio input
     device. An output port sends a single real-time stream of audio data to
     an output device or devices.

     A single application may have multiple ports open simultaneously, or
     multiple applications may have ports open, either sharing audio devices
     or using multiple audio devices. There is, however, a system-dependent
     limit to the total number of audio ports active on a given system.

     This limit can be found by retrieving the value of the AL_MAX_PORTS
     parameter on the AL_SYSTEM resource; see alParams(3dm) and
     alGetParams(3dm) for information on how to do this.

     As soon as the call to alOpenPort completes successfully, the port is
     considered "open." This means it will be filling or draining audio data
     in real-time at the rate of the audio device to which the port is
     connected. The application must read or write enough data frequently
     enough that the port does not underflow or overflow. Refer to
     alReadFrames(3dm), alWriteFrames(3dm), alDiscardFrames(3dm), and
     alZeroFrames(3dm) for more information on how to read and write audio
     data to and from a port.


     Also note that an open audio port consumes CPU and memory resources even
     if the application is not actively reading or writing audio data. If your
     application is not using an audio port, it is best to close it.

     The default port has a 50,000 sample frame stereo buffer, using a 16-bit
     two's complement sample format.

DIAGNOSTICS
     If successful, alOpenPort(3dm) returns a non-zero ALport handle for the
     port.  Otherwise, alOpenPort(3dm) returns a null (0) ALport and sets an
     error code, which can be retrieved via oserror(3C).

     alOpenPort can fail with the following error codes:

     AL_BAD_CONFIG          config is invalid.

     AL_BAD_DIRECTION       direction is neither "r" nor "w."

     AL_BAD_OUT_OF_MEM      insufficient memory is available to allocate the
                            ALport, or in the case of subcode ports, another
                            subcode port is currently writing the same subcode
                            format to the device.

     AL_BAD_DEVICE_ACCESS   audio hardware is not available, or is improperly
                            configured.

     AL_BAD_DEVICE          the device given in the config is bad, either
                            because it does not exist, or because it has the
                            wrong direction (input vs. output).

     AL_BAD_NO_PORTS        no audio ports are currently available.
                            AL_BAD_SAMPFMT the device given in the config does
                            not support the sample format given in the config.
                            This should only occur if a device does not
                            support a subcode sample format.

SEE ALSO
     alClosePort(3dm), alNewConfig(3dm), alSetConfig(3dm), ALqueryparams(3dm),
     oserror(3C)


                                                                        Page 2