NAME

t_addleaf - add a leaf to a point-to-multipoint connection

SYNOPSIS

#include <xti.h>

int32_t t_addleaf(fd, leafid, addr, int32_t fd, int32_t leafid,
    struct netbuf *addr);

DESCRIPTION

Parameters	Before call	After call
fd	x	/
leafid	x	/
addr.maxlen	/	/
addr.len	x	/
addr.buf	x (x)	/

This function enables a transport user to add a leaf to a point-to-multipoint connection. This function can only be issued in the T_DATAXFER state. The parameter fd identifies the local transport endpoint that serves as the root of the point-to-multipoint connection. The parameter leafid, provided by the transport user, will be used by subsequent functions t_removeleaf() and t_rcvleafchange() to identify the particular leaf being added. The parameter addr is the address of the device being added as a leaf.

The values used for leafid may be used simultaneously on point-to-multipoint connections other than the connection indicated by fd.

By default, t_addleaf() executes in synchronous mode, and will wait for the remote leaf user's response before returning control to the local user. A successful return (that is, return value of zero) indicates that the requested leaf has been added to the connection. However, if O_NONBLOCK is set (via t_open() or fcntl()), t_addleaf() executes in asynchronous mode. In this case, the call will not wait for the remote leaf user's response, but will return control immediately to the local user and return -1 with t_errno set to [TNODATA] to indicate that the leaf has not yet been added. In this way, the function simply initiates the leaf addition procedure by sending an "add leaf" request to the remote leaf user. The t_rcvleafchange() function is used in conjunction with t_addleaf() to determine the status of the requested leaf addition.

VALID STATES

T_DATAXFER

ERRORS

On failure, t_errno is set to one of the following:

[TBADF]

The specified file descriptor does not refer to a transport endpoint. Also used when the connection is not point-to-multipoint.

[TNODATA]

O_NONBLOCK was set, so the function successfully initiated the leaf addition procedure, but did not wait for a response from the remote leaf user.

[TBADADDR]

The specified address was in an incorrect format or contained illegal information.

[TADDRBUSY]

This transport provider does not support more than one instance of a particular leaf on a given point-to-multipoint connection. This error indicates that the leaf is already a participant in the point-to-multipoint connection.

[TOUTSTATE]

The function was issued in the wrong sequence on the transport endpoint referenced by fd.

[TNOTSUPPORT]

This function is not supported by the underlying transport provider.

[TSYSERR]

A system error has occurred during execution of this function.

[TLOOK]

An asynchronous event, which requires attention, has occurred.

[TPROTO]

This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI t_errno return code.

RETURN VALUE

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and t_errno is set to indicate the error.

SEE ALSO

t_removeleaf(), t_rcvleafchange().

ATM PROTOCOL SPECIFICS

The parameter addr is filled with a t_atm_addr structure and represents the ATM network address of the leaf being added.