t_bind(3xti_ipx)


t_bind -- bind a socket to a transport endpoint

Synopsis

#include "ipx_app.h" 

int t_bind( int ipxFd, struct t_bind *req, struct t_bind *ret )

Parameters

(IN) ipxFd
Passes the file descriptor that was returned by t_open.

(IN) req
Passes a pointer to (or the address of) a t_bind structure that in turn points to a structure that contains the requested address. The socket value in the structure is initialized to either a static socket number (one you have been assigned) or to zero (to obtain a dynamic socket number).

(IN) ret
Passes a pointer to (or the address of) a t_bind structure that in turn points to a structure that contains the IPX(TM) address. The pointer can point to and be the same structure that contains the requested address, req.

(OUT) ret
Receives the full IPX address: network address, node address, and socket number of the bound transport endpoint.

Return values

0
Successful

-1
Unsuccessful
If t_bind returns an error, both errno and t_errno may be set. t_errno may be set to one of the following:

TBADADDR
The requested socket number is in use.

TNOADDR
There are no unused dynamic socket numbers. The IPX user should try again.

TOUTSTATE
This connection is in a state that invalidates a t_bind request.

TSYSERR
A system error occurred during the t_bind call. See the values for errno.
If t_errno is set to TSYSERR, errno may be set to the following:

ENOSR
No message buffers were available to acknowledge the bind request.
See t_bind(3xti) for other possible errors.

Remarks

The t_bind function binds an endpoint to an IPX socket. This means that it associates a protocol address with a given transport endpoint.

The t_bind function is supported as documented in ``Programming with the X/Open Transport Interface (XTI)'' and t_bind(3xti) with the following additions.

The t_bind structure has the following format:

   struct t_bind { 
      struct netbuf  addr; 
      unsigned int   qlen; 
   }; 
IPX does not use the ``qlen'' field. It should be set to zero.

The netbuf structure has the following format:

   struct netbuf { 
      unsigned int  maxlen; 
      unsigned int  len; 
      char          *buf; 
   }; 
The t_bind call requires that a pointer to an ipxAddr_t type structure be passed in the req t_bind structure (req.addr.buf field).

The ipxAddr_t structure has the following format:

   typedef struct ipxAddress { 
      unsigned char net[ 4 ]; 
      unsigned char node[ 6 ]; 
      unsigned char sock[ 2 ]; 
   }ipxAddr_t; 
The t_bind call allows an application to bind to a socket number, which can be either dynamic or static. IPX keeps track of which socket number is bound to which transport endpoint.

Static socket numbers

To obtain a static socket number, complete the following steps:

  1. Allocate an ipxAddr_t structure.

  2. Set the socket value in the ipxAddr_t structure. The example on the following page uses two #defines to specify the socket number and to ensure that the socket number is passed in hi-lo format.

  3. Allocate a t_bind structure.

  4. Initialize the t_bind structure's fields. The req.addr.buf field must point to the ipxAddr_t structure allocated in Step 1.

  5. Make the t_bind call by passing the ipxFd value returned in your t_open call and by passing the address of the t_bind structure allocated in Step 3 as both the req and the ret values.
The IPX driver looks at the socket field in the ipxAddr_t structure for the IPX user's desired socket number. The socket number must be passed in hi- lo byte order.

If the socket number desired is not currently being used by another IPX user, the IPX driver returns the local net, local node, and the allocated or requested socket number in the corresponding fields of the ipxAddr_t structure of the ret.addr.buf field.

Only one IPX endpoint can bind to a given socket number at a time. If the user tries to bind to a socket that has already been bound to, an error results and the bind fails.

Services written to run over IPX generally have well-known or static socket numbers associated with them. (Contact Novell to obtain a static socket number.) By having static socket numbers, IPX users ensure that their server and client application types match.

Another method to coordinate servers and clients is to use the Service Advertising Protocol (SAP). For programming information, see Chapter 8, "SAP Library,"on page 233.

Dynamic socket number

A dynamic socket number is an unused socket number and is guaranteed to be a unique unused number among the IPX endpoints. A dynamic socket is a value from 0x4000 to 0x7FFF.

There are two methods for obtaining a dynamic socket number.

Regardless of which method you choose, if you do not need the address that has been bound, you can pass NULL as ret.

Examples

   #define SOCKET_TO_BIND_HIGH 0x45 /*high order byte */ 
   #define SOCKET_TO_BIND_LOW 0x00 /*low order byte */ 
   

struct t_bind bind; ipxAddr_t localAddress;

localAddress.sock[0] = SOCKET_TO_BIND_HIGH; localAddress.sock[1] = SOCKET_TO_BIND_LOW;

bind.addr.len = sizeof(ipxAddr_t); bind.addr.maxlen = sizeof(ipxAddr_t); bind.addr.buf = (char *)&localAddress; bind.qlen = 0;

if (t_bind(ipxFd, &bind, &bind)<0) { t_error( "t_bind failed"); ... }

State

The state follows the state diagram in ``State transitions''.

References

t_bind(3xti), t_open(3xti_ipx), t_unbind(3xti)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.