alConnect(3dm)                                                  alConnect(3dm)


NAME
     alConnect - connect two audio I/O resources

SYNOPSIS
     #include <dmedia/audio.h>

     int alConnect(int source, int dest, ALpv *props, int nprops)

PARAMETER
     source   is the source resource.

     dest     is the destination resource.

     props    is a parameter/value list of desired properties for the
              connection (see alGetParams(3dm) for more information on
              parameter/value lists).

     nprops   is the number of parameter/value pairs in the list props.

DESCRIPTION
     An audio connection moves audio data from one audio I/O resource to
     another. For example, when an application opens an audio input port, the
     audio system creates a connection from an input device to the input port.
     See alResources(3dm) for information on resources in general.

     alConnect creates a connection from the resource source to the resource
     dest. alConnect can connect a port to a device, a device to a port, or a
     device to a device; port-to-port connections are not supported at this
     time. Other types of resources cannot be connected.

     In addition, there are certain constraints on the directions of source
     and dest. source must be either an input device or an output port. dest
     must be either an output device or an input port.

     A connection performs certain operations on the audio data.  These
     operations are given by the properties list props.  See below for the
     currently supported properties. If nprops is 0, the connection will be
     given a default set of properties.

     If a connection already exists between the given source and dest,
     alConnect will return the resource ID of the existing connection and set
     the given properties props on that connection.

     Note that by default, connections persist after the application which
     creates them exits. In order to remove the connection, you must
     explicitly call alDisconnect(3dm), or create the connection with the
     AL_ASSOCIATE property.

     Only one property is currently supported for connections, AL_ASSOCIATE,
     which allows you to associate a connection with a particular port.
     AL_ASSOCIATE takes as its value the resource ID of a port (see
     alGetResource(3dm)).  When the port is destroyed, the connection is


     destroyed as well. This allows an application to create a connection
     which is guaranteed to go away when the application goes away.

EXAMPLES
     The following simple program takes two device names as command-line
     arguments and creates a connection between them.  This connection will
     persist after the program exits.

          main(int argc, char **argv)
          {
               int fd;
               int src, dest;
               int id;

               if (argc != 3) {
                  printf("usage: %s <src> <dest>\n",argv[0]);
                  exit(-1);
               }

               /* Find the source resource */
               src = alGetResourceByName(AL_SYSTEM, argv[1], AL_DEVICE_TYPE);
               if (!src) {
                  printf("invalid device %s\n", argv[1]);
                  exit(-1);
               }

               /* Find the destination resource */
               dest = alGetResourceByName(AL_SYSTEM, argv[2], AL_DEVICE_TYPE);
               if (!dest) {
                  printf("invalid device %s\n", argv[2]);
                  exit(-1);
               }

               /* Attempt to connect them */
               if ((id = alConnect(src, dest, 0, 0))<0) {
                  printf("connect failed: %s\n",alGetErrorString(oserror()));
               }
               printf("connection ID is %d\n",id);
          }


     The following code fragment creates a connection which goes away when a
     port goes away. Since the port is tied to the application, this
     connection does not persist after the application exits.  This particular
     example creates a port which does not actually do audio; it is connected
     to no audio device. We also give it a minimal queue size so that it
     consumes few audio resources.


               ALport p;
               ALconfig c;
               ALpv pv;
               int id, src, dest;

               /* code here to set src & dest */

               [...]

               /* create a config structure */
               c = alNewConfig();
               if (!c) {
               printf("alNewConfig failed: %s0,alGetErrorString(oserror()));
               exit(-1);
               }

               /* set the config so the port does no audio */
               alSetDevice(c, AL_NULL_RESOURCE);
               alSetQueueSize(c, 100);

               /* now open a port using the config */
               p = alOpenPort("null port","r",c);
               if (!p) {
               printf("alOpenPort failed: %s0,alGetErrorString(oserror()));
               exit(-1);
               }

               /* Attempt to connect src & dest. We assume that these are set
               to valid resource IDs. */

               pv.param = AL_ASSOCIATE;
               pv.value.i = alGetResource(p);

               if ((id = alConnect(src, dest, &pv, 1))<0) {
                  printf("connect failed: %s\n",alGetErrorString(oserror()));
               }
               printf("connection ID is %d\n",id);

               /* now, when we close the port, or the application exits (also
               closing the port), the connection will automatically go away */
               [...]


DIAGNOSTICS
     If successful, alConnect returns the resource ID of the connection.  It
     returns -1 if the connection fails, and sets an error code which can be
     retrieved with oserror(3C).

     alConnect can fail for the following reasons:


     AL_BAD_RESOURCE
          source or dest is an invalid resource.

     AL_BAD_DEVICE_ACCESS
          The audio system is not present or improperly configured.

     AL_BAD_PVBUFFER
          props is invalid and nprops is nonzero.

     AL_BAD_BUFFERLENGTH
          nprops is less than zero.

SEE ALSO
     oserror(3C), alIntro(3dm), alGetParams(3dm), alDisconnect(3dm)


                                                                        Page 4