vlgetconnection(3dm)

NAME
     vlGetConnection - manage the connectivity of a VL path

SYNOPSIS
     #include <dmedia/vl.h>

     int vlGetConnection(VLServer svr, VLPath path,
                         VLNode node, VLPort port,
                         VLNode *nodelist, VLPort *portlist,
                         int *n);


PARAMETERS
     svr       Specifies the server handle.

     path      Specifies the path handle.

     node      Specifies the node to get connection information from.

     port      Specifies the port to get connection information from.

     nodelist

     portlist  On return, (nodelist[i], portlist[i]) specify the source or
               target connections to (node, port).

     n         On entry, n points to an integer value specifying the size of
               the nodelist and portlist arrays. On exit, n is updated to
               reflect the actual number of connections returned.

DESCRIPTION
     vlGetConnection obtains connection information about (node, port).

     If (node, port) specifies a source port, then all currently connected
     targets of that port are returned in the nodelist and portlist arrays,
     and *n is updated to reflect the number of targets.

     If (node, port) specifies a drain port, then it can have at most one
     source connection returned in the nodelist and portlist arrays.

     If (node, port) is not connected, then *n is set to 0.

     If a source or target of (node, port) cannot be represented on the given
     path, then (VLUnknownNode, VLUnknownPort) is returned in the nodelist and
     portlist arrays. This may happen if multiple paths share a node, and one
     path creates a connection to a node on its path but not on the other
     paths.

     If vlGetConnection is called with a value of *n which is not large enough
     to contain entries for all connections, a value of -1 is returned,
     vlErrno is set to VLNotEnoughSpace, and *n is set to the number of
     entries necessary to describe all connections.
     Calls to vlGetConnection can be made on any path that has been setup
     (i.e. has a stream and control usage other than VL_DONE_USING).


RETURN VALUE
     If successful, this functions returns zero. A return value of -1
     indicates an error, and vlErrno is set to one of the following:


     VLBadServer           The server parameter is not valid.

     VLBadPath             The path is not valid.

     VLBadNode             The source or target node is not a valid node on
                           the path.

     VLBadAccess           The path has not been setup.

     VLBadAlloc            A memory allocation attempt failed.

     VLNotSupported        vlGetConnection is not supported on the device.

     VLBadImplementation   An internal processing error has occurred.

     VLNotEnoughSpace      Nodelist or portlist array does not contain enough
                           entries to describe all connections.

SEE ALSO
     vlSetConnection(3dm), vlSetupPaths(3dm), vlBeginTransfer(3dm)