Table of Contents

Name

linx_request_new_link() - request a new link signal.
linx_cancel_new_link() - cancel a new link request.

Synopsis

#include <linx_types.h>
#include <linx.h>

LINX_NLREF linx_request_new_link(LINX *linx, LINX_NLTOKEN token);

int linx_cancel_new_link(LINX *linx, LINX_NLREF *nlref);

Description

Request a new link signal from LINX when a new LINX link is available. The token is passed back and forth between the calling LINX endpoint and the LINX kernel module to keep track of which LINX link was sent in the last new link signal. The first time a LINX endpoint calls linx_request_new_link() the value of the token is ignored. The token is then returned in the new link signal from the LINX kernel module and should be used by the LINX endpoint in the next linx_request_new_link() call. If a LINX link unknown to the LINX endpoint is present when the linx_request_new_link() call is made a new link signal is immediately sent to the caller. Two or more consecutive calls to linx_request_new_link() are allowed from the same LINX endpoint. The linx_request_new_link() call returns a reference handle which is used in the linx_cancel_new_link() call if a request is to be cancelled. After a cancellation no more new link signals are received if the socket has no other pending new link requests.

linx is the handle of the own LINX endpoint.

token is passed back and forth between the calling LINX endpoint and the LINX kernel module.

nlref is the reference used to cancel a pending new link request.

The syntax of the new link signal received when a new link is available is: 


struct linx_new_link {
    LINX_SIGSELECT signo;
    LINX_NLTOKEN token;
    int name;
    int attr;
    char buf[1];
};

signo is LINX_OS_NEW_LINK_SIG, token is the token value to be used in the next request for a new link signal, name is the offset into buf where the name of the new link is stored, the name is null terminated, attr is the offset into buf where the attributes, if any, of the link are stored, the attribute string is null terminted, buf is a character buffer containg the name and the attributes, if any, of the link.

Return Value

linx_request_new_link() returnes an new link reference (LINX_NLREF) when successful, otherwise on failure LINX_ILLEGAL_NLREF is returned. linx_cancel_new_link() returns 0 on success and -1 on failure. In case of failure errno will be set.

Errors

EBADF The linx handle refers to an invalid socket descriptor.

ENOMEM Insufficient memory is available.

EINVAL Returned by linx_cancel_new_link() when trying to cancel an non-existent new link request.

Bugs/Limitations

None.

See Also

linx(7)

Author

Enea LINX team

Copyright

Copyright (c) 2006-2007, Enea Software AB All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of Enea Software AB nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Table of Contents