Developing applications over NetBIOS using XTI

How XTI functions behave differently over NetBIOS

Be aware of the following special considerations when using XTI functions over a NetBIOS provider. The XTI functions are listed in alphabetical order.

t_accept

This function never returns any user data to the caller. Consequently, the value of call->udata.len is always zero.

If you call this function for a connectionless transport provider, the function returns -1 and t_errno is set to TNOTSUPPORT.

t_alloc

There are no special considerations when calling this function over a NetBIOS transport provider.

t_bind

In addition to specifying the name you wish to bind in the nb_name field of the struct nb_addr structure, you must set the nb_type field to either NB_UNIQUE or NB_GROUP. If the transport provider cannot bind the NetBIOS name to the transport endpoint, the t_bind returns -1 and t_errno is set to:

TADDRBUSY if the name is already in use
TBADADDR if the name is not a legal NetBIOS name

Only one process on the LAN can bind a given name with a type of NB_UNIQUE to a transport endpoint. If a process successfully binds a name with a type of NB_UNIQUE to a transport endpoint, and another process later attempts to bind the same name to a transport endpoint (whether it specifies NB_UNIQUE or NB_GROUP in the nb_type field), the error TADDRBUSY is returned to that other process. Only one process on the LAN can bind a name of type NB_UNIQUE.

However, multiple processes can bind the same name to their transport endpoints, provided that each one sets the nb_type field to NB_GROUP when calling t_bind. Group names are useful for logically segmenting the LAN. You can implement multicasting (the sending of datagrams to some, but not all of the hosts on a LAN) by specifying a group name when you send a datagram.

t_close

There are no special considerations when calling this function over a NetBIOS transport provider.

t_connect

If this function succeeds in establishing a connection, the NetBIOS name that the transport provider returns in rcvcall->addr.buf will always be the same as the name specified in sndcall->addr.buf.

You cannot send user data during session establishment. Therefore, sndcall->udata.len must be zero. This field will be set correctly if you call t_alloc to allocate sndcall.

Do not call this function over a connectionless transport endpoint. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

With some NetBIOS providers, (but not SCO TCP/NetBIOS or NetBEUI) it is possible for the NetBIOS name you bound to the transport endpoint to be removed by the transport provider as a result of a name conflict resolution protocol. If the name is removed between the call to t_bind and the call to t_connect, t_connect returns -1 and t_errno is set to TBADF. See the documentation supplied with transport provider software for more information.

t_error

There are no special considerations when calling this function over a NetBIOS transport provider.

t_free

There are no special considerations when calling this function over a NetBIOS transport provider.

t_getinfo

These fields are part of the the t_info structure returned by t_getinfo:

addr: always contains the value of sizeof(struct nb_addr).
options: always contains the value of -2. This indicates that no user-settable options are supported.
etsdu: always contains the value of -2. This indicates that you cannot send expedited data.
connect: always contains the value of -2. This indicates that you cannot send user data while establishing a connection.
discon: always contains the value of -2. This indicates that you cannot send user data while releasing a connection.
flags: always has the T_SENDZERO bit turned on. This indicates that you can send zero-length TSDUs (Transport Service Data Units).

t_getstate

There are no special considerations when calling this function over a NetBIOS transport provider.

t_listen

You cannot send user data during connection establishment over a NetBIOS transport provider. Consequently, call->udata.len equals zero when the function returns.

Do not call this function over a connectionless transport endpoint. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

t_look

Because you cannot send expedited data over NetBIOS transports, t_look never returns the events T_EXDATA and T_GOEXDATA.

t_open

These fields are part of the the t_info structure returned by t_open:

addr: always contains the value of sizeof(struct nb_addr).
options: always contains the value of -2. This indicates that no user-settable options are supported.
etsdu: always contains the value of -2. This indicates that you cannot send expedited data.
connect: always contains the value of -2. This indicates that you cannot send user data while establishing a connection.
discon: always contains the value of -2. This indicates that you cannot send user data while releasing a connection.
flags: always has the T_SENDZERO bit turned on. This indicates that you can send zero-length TSDUs (Transport Service Data Units).

t_optmgmt

There are no special considerations when calling this function over a NetBIOS transport provider.

t_rcv

Do not call this function over a connectionless transport endpoint. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

Because you cannot send expedited data over NetBIOS transports, the T_EXPEDITED flag in the flags parameter is never set.

t_rcvconnect

You cannot send user data during connection establishment over a NetBIOS transport provider. Consequently, call->udata.len equals zero when the function returns.

Do not call this function over a connectionless transport endpoint. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

t_rcvdis

The disconnect reason codes listed below are supported by all valid NetBIOS transport providers that conform to the XPG4 specification of XTI. Following each reason code is the hexadecimal value of the equivalent reason code in PC NetBIOS.

NB_ABORT: session ended abnormally
NB_CLOSED: session closed
NB_NOANSWER: no answer, cannot find called name
NB_OPREJ: session open rejected

The function returns the reason code in the discon->reason field of the struct t_discon parameter.

t_rcvrel

Do not call this function over either a connectionless transport endpoint or connection-oriented transport endpoint without orderly release. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

NOTE: SCO TCP/NetBIOS and NetBEUI do not support connection-oriented service with orderly release. Therefore, you should never need to call t_rcvrel when using either of these two transports. Also, using t_rcvrel (and t_sndrel), even over NetBIOS transports that support these functions, limits portability and is not recommended.

When a transport user sends an orderly release request by calling t_sndrel, the transport user that receives the request sees the T_DISCONNECT event, not the T_ORDREL event. Therefore, the transport user receiving the request calls t_rcvdis to consume the event, not t_rcvrel.

To complete the orderly release handshake, the transport provider that receives the orderly release request transparently sends a release response to the originating transport endpoint. The originating transport user sees the T_ORDREL event, and consumes it by calling t_rcvrel.

t_rcvudata

Do not call this function over a connection-oriented transport endpoint. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

If you want to receive broadcast datagrams, you must bind the name NB_BCAST_NAME to the transport endpoint.

t_rcvuderr

Because there are no unit data error codes defined for XTI over NetBIOS, do not call this function. If you do, the function returns -1, and t_errno is set to TNOUDERR.

t_snd

Do not set the T_EXPEDITED flag, because NetBIOS does not support the sending of expedited data. If you do, and you are using SCO TCP/NetBIOS, the function returns -1, and t_errno is set to TNOTSUPPORT. However, if you are using NetBEUI, the function returns zero and the flag is ignored.

Do not call this function over a connectionless transport endpoint. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

The following information applies if you are using SCO TCP/NetBIOS or NetBEUI. If, when you call t_snd:

your transport provider has been notified that the remote user has disconnected, and
your transport provider still has buffered data received from the remote user before the disconnect occurred

the function will return zero, but the data to be sent will be discarded. The next XTI function called will return TLOOK, and the call to t_look will return T_DISCONNECT.

t_snddis

Because NetBIOS transport providers do not support the sending of data with a disconnect request, set the call parameter to t_snddis to NULL.

Do not call this function over a connectionless transport endpoint. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

t_sndrel

Do not call this function over either a connectionless transport endpoint or a connection-oriented transport endpoint without orderly release. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

NOTE: SCO TCP/NetBIOS and NetBEUI do not support connection-oriented service with orderly release. Therefore, never call t_sndrel when using either of these two transports. Also, using t_sndrel (and t_rcvrel), even over NetBIOS transports that support these functions, limits portability and is not recommended.

t_sndudata

Do not call this function over a connection-oriented transport endpoint. If you do, the function returns -1, and t_errno is set to TNOTSUPPORT.

If you want to send a broadcast datagram with t_sndudata, you must specify the name NB_BCAST_NAME. Assign this name to the nb_name field of the struct nb_addr structure pointed to by unitdata->addr.buf.

t_sync

There are no special considerations when calling this function over a NetBIOS transport provider.

t_unbind

This function disassociates the NetBIOS name from the specified transport endpoint. The NetBIOS transport provider will also delete this name from the NetBIOS name table if no other transport endpoint is currently bound to that name.

Next topic: How PC NetBIOS is different from XTI over NetBIOS
Previous topic: Creating NetBIOS sessions

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