Developing applications over NetBIOS using XTI

Annotated code sample

The following code implements a client and server that communicate using XTI over a NetBIOS connection. The server opens the file logfile, reads the contents in 1K chunks, and sends each chunk to the client. The client reads each chunk of data over the NetBIOS connection, then writes it to the standard output.

This code has at least two interesting features:

Example NetBIOS client

  1 #include <stdio.h>
  2 #include <fcntl.h>
  3 #include <xti.h>

4 #define SRV_NAME "NB-XTI-DEMO-SERV" 5 #define RFCNBPATH "/dev/nbcots" 6 #define NBEPATH "/dev/netbeui"

7 extern int t_errno;

8 main (int argc, char *argv[]) 9 { 10 int flags = 0; 11 char *netpath = RFCNBPATH; 12 int fd; 13 int nbytes; 14 struct t_call *sndcall; 15 struct nb_addr srv_addr; 16 struct { 17 unsigned short length; 18 char buf[1024]; 19 } msg;

20 if ((fd = t_open(netpath, O_RDWR, (struct t_info *) NULL)) < 0) { 21 t_error("t_open failed"); 22 exit(1); 23 }

24 if (t_bind(fd, (struct t_bind *) NULL, 25 (struct t_bind *) NULL) < 0) { 26 t_error("t_bind error"); 27 exit(2); 28 }

29 if ((sndcall = 30 (struct t_call *)t_alloc(fd, T_CALL, T_ADDR)) == NULL) { 31 t_error("t_alloc failed"); 32 exit(3); 33 }

34 sndcall->addr.len = sizeof(srv_addr); 35 sndcall->addr.buf = (char *)&srv_addr;

line 2
includes the header file that defines the flags O_RDWR and O_NONBLOCK that can be passed in the flags argument to t_open (see line 21).

line 4
defines the name used to identify the server. Replace the string in this line with the name of the server on your network.

line 5
defines a symbol for the device name of the connection-oriented SCO TCP/NetBIOS transport.

line 6
defines a symbol for the device name of the connection-oriented NetBEUI transport.

line 7
declares the global variable used by all XTI routines to report an error.

line 10
initializes the flags argument that will be passed into t_rcv.

line 11
assigns the device name of the transport provider to open. Use the value NBEPATH (instead of RFCNBPATH) to access NetBEUI.

line 15
declares the variable that will contain the NetBIOS name of the server to be contacted.

lines 16-19
declare the data structure defined by this application for each chunk of data to be received. The buf field is a buffer to hold 1K of data. The length field is used to implement in the application itself a client/server handshake equivalent to orderly release.

line 20
opens a connection-oriented transport endpoint (netpath) with full duplex communication (O_RDWR). Because O_NONBLOCK is not specified along with O_RDWR, t_connect and t_rcv will block until either they succeed or an error is detected. To specify both O_RDWR and O_NONBLOCK, you would code
   t_open(netpath, O_NONBLOCK | O_RDWR, (struct t_info *)NULL)

lines 24-25
let the transport provider bind whatever name it chooses to the transport endpoint (the first NULL), and the client does not care to be informed what name was chosen (the second NULL). This is the normal case for a client.

lines 29-30
allocate a struct t_call data structure. The fields of the structure will be assigned the NetBIOS address information.

line 34
initializes the length field of the struct netbuf data structure.

line 35
initializes the pointer field in the struct netbuf data structure with the address of the buffer where the NetBIOS address information will be stored.
 36     srv_addr.nb_type = NB_UNIQUE;
 37     memcpy(srv_addr.nb_name, SRV_NAME, NB_NAMELEN);

38 if (t_connect(fd, sndcall, (struct t_call *) NULL) < 0) { 39 t_error("t_connect failed for fd"); 40 exit(4); 41 }

42 while ((nbytes = t_rcv(fd, &msg, sizeof(msg), &flags)) >= 43 sizeof(msg.length)) { 44 if (fwrite(msg.buf, 1, msg.length, stdout) < 0) { 45 fprintf(stderr, "fwrite failed"); 46 exit(5); 47 } 48 if (msg.length == 0) 49 break; 50 }

51 if (nbytes == sizeof(msg.length) && msg.length == 0) { 52 if (t_snddis(fd, NULL) < 0) { 53 t_error("t_snddis failed"); 54 exit(6); 55 } 56 exit(0); 57 }

58 if (nbytes < sizeof(msg.length)) { 59 fprintf(stderr, "received invalid message, hanging up"); 60 t_snddis(fd, (struct t_call *) NULL); 61 exit(7); 62 } 63 else { 64 if (t_errno == TLOOK) { 65 if (t_look(fd) == T_DISCONNECT) { 66 printf("Got T_DISCONNECT, doing t_rcvdis"); 67 if (t_rcvdis(fd, (struct t_discon *) NULL) < 0) { 68 t_error("t_rcvdis failed"); 69 exit(8); 70 } 71 exit(0); 72 } 73 } 74 else { 75 t_error("t_rcv failed"); 76 exit(9); 77 } 78 } 79 }

line 36
indicates that the name of the server to be contacted is a unique name, not a group name.

line 37
initializes the name field of the struct nb_addr structure with the name of the server.

line 38
connects to the server.

line 42
reads nbytes of data through the transport endpoint. The first two bytes are read into msg.length. The remaining bytes are read into msg.buf.

line 43
writes msg.length bytes of data from msg.buf to the standard output.

lines 48-57
check if the number of bytes sent was zero. This is the signal from the server that no more data will be sent. The client then exits normally. This is the protocol used by this sample application to implement the semantics of orderly release over a transport provider (NetBIOS) that provides only an abortive disconnect (using t_snddis).

lines 58-62
check if the client received the length field of the message. If not, something went wrong. The client bails out by disconnecting. A more robust client might implement an error recovery mechanism.

lines 64-73
check if an asynchronous event has occurred. If the client has received a disconnect request, it consumes the event by calling t_rcvdis, then exits normally (line 71).

lines 75-76
implement the client's error recovery algorithm. This code is reached only if an error has occurred on the call to t_rcv on line 42. The client could check what error has occurred by examining the value of t_errno. In this example, the client simply gives up.

Example NetBIOS server

  1 #include <stdio.h>
  2 #include <signal.h>
  3 #include <stropts.h>
  4 #include <xti.h>
  5 #include <fcntl.h>

6 #define SRV_NAME "NB-XTI-DEMO-SERV" 7 #define RFCNBPATH "/dev/nbcots" 8 #define NBEPATH "/dev/netbeui" 9 #define DISCONNECT -1

10 extern int t_errno; 11 void run_server(int); 12 int conn_fd; 13 char *netpath = RFCNBPATH;

14 main(int argc, char *argv[]) 15 { 16 int listen_fd; 17 struct t_bind *bind; 18 struct t_call *call; 19 struct nb_addr srv_addr; 20 struct nb_addr client_addr;

21 if ((listen_fd = 22 t_open(netpath, O_RDWR, (struct t_info *) NULL)) < 0) { 23 t_error("t_open failed for listen_fd"); 24 exit(1); 25 }

26 if ((bind = (struct t_bind *)t_alloc(listen_fd, T_BIND, T_ADDR)) 27 == NULL) { 28 t_error("t_alloc of t_bind structure failed"); 29 exit(2); 30 }

line 12
declares the variable that will identify the transport endpoint to be used by the child process (to be spawned later) when it communicates with the client. The variable happens to be global in this example to avoid passing it around as a parameter. It is referenced both by main and run_server.

line 13
assigns the device name of the transport to be used. Use the value NBEPATH instead of RFCNBPATH to access NetBEUI.

line 16
declares the variable to be used by the parent process to identify the transport endpoint that the parent process will use to listen for incoming connection requests.

lines 21-22
open a connection-oriented full-duplex transport endpoint in non-blocking mode. The third argument is set to NULL in this example, indicating that the server does not care to examine any of the transport provider's attributes.

lines 26-27
allocate the struct t_bind data structure to be used in the call to t_bind.
 28     bind->qlen = 5;
 29     bind->addr.len = sizeof(srv_addr);
 30     bind->addr.buf = (char *)&srv_addr;

31 srv_addr.nb_type = NB_UNIQUE; 32 memcpy(srv_addr.nb_name, SRV_NAME, NB_NAMELEN);

33 if (t_bind(listen_fd, bind, bind) < 0) { 34 t_error("t_bind failed for listen_fd"); 35 exit(3); 36 }

37 if (memcmp(srv_addr.nb_name, SRV_NAME, NB_NAMELEN) != 0) { 38 fprintf(stderr, "t_bind bound wrong address\n"); 39 exit(4); 40 }

41 if ((call = (struct t_call *)t_alloc(listen_fd, T_CALL, T_ADDR)) 42 == NULL) { 43 t_error("t_alloc failed"); 44 exit(5); 45 } 46 call->addr.len = sizeof(srv_addr); 47 call->addr.buf = (char *)&client_addr;

48 while (1) { 49 if (t_listen(listen_fd, call) < 0) { 50 t_error("t_listen failed for listen_fd"); 51 exit(6); 52 } 53 if ((conn_fd = accept_call(listen_fd, call)) != DISCONNECT) 54 run_server(listen_fd); 55 } 56 }

line 28
sets the depth of the queue for incoming connection requests to five.

line 30
points addr.buf to the NetBIOS name structure.

lines 31-32
assign the server's well-known NetBIOS name. The name is termed ``well-known'' because all clients on the network are expected to know this name. The server expects to be the only one on the network with this name, so it assigns the name type a value of NB_UNIQUE.

line 33
binds the server's name and the length of the connection request queue to the transport endpoint. These are specified in the second argument (first occurrence of bind). The third argument points to the same bind data structure specified in the second argument. The transport provider will return in bind->qlen the actual value of the connection request queue length it can support, if that is less than the requested value.

lines 41-42
allocate the struct t_call data structure to be used in the call to t_listen.

lines 46-47
set up the call data structure. call->add.buf will point to the name of the client trying to connect to the server. This value will be filled in by the call to t_listen on line 49.

lines 48-56
loop forever listening for connection requests on one transport endpoint, accepting them on different transport endpoint, then spawning a child process to communicate with the client.

lines 53-54
accept the connection with the client on the new transport endpoint, conn_fd. The server parent process will continue to listen for incoming connection requests on listen_fd, while the child process spawned in run_server will respond to the client. The functions accept_call and run_server are application-level functions, not XTI functions.
 57 int
 58 accept_call(int listen_fd, struct t_call *call)
 59 {
 60     int resfd;

61 if ((resfd = t_open(netpath, O_RDWR, (struct t_info *) NULL)) 62 < 0) { 63 t_error("t_open for responding fd failed"); 64 exit(7); 65 }

66 if (t_bind(resfd, (struct t_bind *) NULL, 67 (struct t_bind *) NULL) < 0) { 68 t_error("t_bind for responding fd failed"); 69 exit(8); 70 }

71 if (t_accept(listen_fd, resfd, call) < 0) { 72 if (t_errno == TLOOK) { 73 if (t_rcvdis(listen_fd, (struct t_discon *) NULL) < 0) { 74 t_error("t_rcvdis failed for listen_fd"); 75 exit(9); 76 } 77 if (t_close(resfd) < 0) { 78 t_error("t_close failed for responding fd"); 79 exit(10); 80 } 81 return(DISCONNECT); 82 } 83 t_error("t_accept failed"); 84 exit(11); 85 }

86 return(resfd); 87 }

88 connrelease() 89 { 90 exit(0); 91 }

lines 57-87
open a new transport endpoint, let the transport bind any valid name to it, then accept the incoming connection request on that endpoint.

line 61
opens a new transport endpoint.

line 66
lets the transport select a NetBIOS name to bind to the endpoint.

line 71
accepts on resfd the connection request received earlier on listen_fd. By accepting the connection request on a file descriptor different from the one on which the connection request was received, the server can fork a child process to handle the client request, while the (parent) server continues to listen for new clients trying to connect on the original file descriptor.

lines 72-82
respond to an asynchronous event. The server assumes the client is now trying to disconnect. The server responds by consuming the disconnect event (line 73) and shutting down the transport endpoint on which it intended to accept the connection (line 77).

An alternative is to call t_look after line 72 to determine precisely what asynchronous event has occurred. The server can then respond appropriately. See the manual page for t_look for a description of the asynchronous events returned by this function.

line 81
returns DISCONNECT to indicate that the connection request was aborted by the client.

line 86
returns the value of the transport endpoint on which the connection request has been accepted.

lines 88-91
declare the signal handler that is set in line 122. If an unexpected input message arrives at the transport endpoint, this handler will be executed. The handler simply exits, tearing down the transport endpoint the server is listening on. The exit also kills all of the child processes that are communicating with clients, thus tearing down their transport endpoints. Clients will receive the T_DISCONNECT asynchronous event at their local transport endpoint.
 92 void
 93 run_server(int listen_fd)
 94 {
 95     int nbytes;
 96     FILE *logfp;

97 struct { 98 unsigned short length; 99 char buf[1024]; 100 } msg;

101 switch (fork()) {

102 case -1: 103 perror("fork failed"); 104 exit(12);

105 default: /* parent */ 106 /* close conn_fd and go up to listen again */ 107 if (t_close(conn_fd) < 0) { 108 t_error("t_close failed for conn_fd"); 109 exit(13); 110 } 111 return;

112 case 0: /* child */ 113 /* close listen_fd and do service */ 114 if (t_close(listen_fd) < 0) { 115 t_error("t_close failed for listen_fd"); 116 exit(14); 117 } 118 if ((logfp = fopen("logfile", "r")) == NULL) { 119 perror("cannot open logfile"); 120 exit(15); 121 }

lines 97-100
declare the variable to hold the next chunk of data to be read from the log file and transmitted to a client.

line 101
spawns a child process to communicate with the client.

lines 105-111
close conn_fd. The parent process executes these lines because it will not be using this transport endpoint. The transport endpoint associated with conn_fd is not destroyed, however, because the child process will leave it open to communicate with the client. The parent returns to the calling function to continue to listen for connections on listen_fd.

lines 112-116
close listen_fd. The child process executes these lines because it will not be using this transport endpoint. The transport endpoint associated with listen_fd is not destroyed, however, because the parent process will leave it open to listen for the next incoming connection request from a client.

lines 118-121
open the log file for reading. The child process executes these lines.
122         signal(SIGPOLL, connrelease);

123 if (ioctl(conn_fd, I_SETSIG, S_INPUT) < 0) { 124 perror("ioctl I_SETSIG failed"); 125 exit(16); 126 }

127 if (t_look(conn_fd) != 0) { 128 fprintf(stderr, "t_look returned unexpected event"); 129 exit(17); 130 }

131 while ((nbytes = fread(msg.buf, 1, 1024, logfp)) > 0) { 132 msg.length = nbytes; 133 if (t_snd(conn_fd, &msg, nbytes + 134 sizeof(msg.length), 0) < 0) { 135 t_error("t_snd failed"); 136 exit(18); 137 } 138 }

139 msg.length = 0;

140 if (t_snd(conn_fd, &msg, 2, 0) < 0) { 141 t_error("can't send 0 bytes"); 142 exit(19); 143 }

144 pause(); /* until disconnect indication arrives */ 145 } 146 }

lines 122-146
list the remaining instructions to be executed by the child process.

line 122
sets connrelease as the SIGPOLL signal handler.

line 123
establishes that a SIGPOLL signal will be generated if an unexpected message arrives at the transport endpoint denoted by conn_fd.

lines 131-138
read from the log file in 1K chunks and send both the data and the number of bytes read to the client.

lines 139-143
signal the end of the file by sending a message with the length field set to zero.

line 144
waits until the SIGPOLL signal is generated. This will occur when the client receives the message with the length field set to zero, because the client will send a disconnect indication to the server by calling t_rcvdis. The signal handler connrelease will then be called, which calls exit to terminate the process.

Next topic: Getting more information
Previous topic: Example for obtaining session and adapter status

© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003