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
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.
-
A dynamic socket number is an unused socket number returned by the IPX driver and is guaranteed to be a unique unused number among the IPX endpoints. The range is a value from 0x4000 to 0x7FFF.
-
A static socket number can be requested in the req t_bind structure. If the socket number is unused, it is granted and returned in the ret t_bind structure. The range is 0x8000 to 0xFFFF and numbers are assigned by Novell.
Static socket numbers
To obtain a static socket number, complete the following steps:
-
Allocate an ipxAddr_t structure.
-
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.
-
Allocate a t_bind structure.
-
Initialize the t_bind structure's fields. The
req.addr.buf
field must point to the ipxAddr_t structure allocated in Step 1.
-
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.
-
If a dynamic socket is wanted, set the sock field in the ipxAddr_t structure to zero (0).
The IPX driver attempts to allocate a dynamic socket number.
-
If a dynamic socket is wanted and you do not need to know the value of the socket number, pass NULL as req.
The IPX driver assumes then that the IPX user has requested a dynamic socket number, and it tries to allocate and to assign 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.