The X.25 library distances the programmer from the nitty-gritty of the streams SPI interface to the X.25 driver. The library will allow the development of applications which will work on Netcom II, Netcom II Streams , Wanware NT, and the Wanware SNA WAN Extensions Set.

The library is partly based on a concept called Tags which it uses to obtain parameters for some functions. Tags should always be passed in pairs: the manifest constant for the tag itself and the value associated with it. (An exception to this is the last tag in the list, which should ALWAYS be TAG_END!) Whenever a function specifies that it accepts a TAG LIST, a variable length argument list is expected to be passed to it. A variation on this is to pass a pointer to the first element of an array of TAG structures to the ...tags() variant of this function.

An example:

    rc = X25makecall(callt, T_OUTPKTSIZE, 256,
                                T_CUD, "\01\00\00\00C",
                                T_CUDLEN, 5,
                                TAG_END);

X25clear(ct, diag_known ? T_DIAG : T_IGNORE, 0x80, TAG_END);

TAGS mytags[] = { {T_DIAG, 0x80}, {TAG_END, 0} };
X25cleartags(ct, mytags);

Most functions will return 0 for success or -1 for failure.

Error handling is done by looking at the value of the variable x25errno or calling the library function X25error() to print out an explanation for the error. Please see libx25.h for a list of currently defined error codes.

Before using X25getnetent, the function X25setnetent must be called which allocates necessary resources and enables the library to access the configuration database. At this point X25getnetent can be used to scan through the list of Frame Relay netids in the system. An optional filter can be specified using X25setfilter to limit or increase the types of Netids returned by X25getnetent. To release the resources allocated by X25setnetent, call X25endnetent.

The functions X25getnetbynetid and X25getnetbyname use the above functions to search through the configuration database to locate the desired Netid. These functions do not require the calling application to use X25setnetent or X25endnetent.

The x25hostent structure is defined in libx25.h It contains the name of the host, the DNA (X.121 Address), the network ID, flags specifying special options for the host, and a partially filled call request structure.

All host file access functions will return a pointer to a static area which will be overwritten by the next call to a host file access function.

The functions to enumerate hosts in the x25hosts file are: X25sethostent to initialize file access, X25gethostent to retrieve one host from the file, and X25endhostent to terminate file access. Functions to search for a specific host are: X25gethostbyaddr to retrieve a x25hostent structure associated with a given DNA (X.121 address) and Network ID, and X25gethostbyname to retrieve a x25hostent structure associated with a logical host name.

If only one circuit is to be monitored, then using X25lookatone is the simplest method. However, this approach does not easily scale when 2 or more circuits require monitoring.

The recommended method for multi-circuit applications is to use the X25lookxxxx series of functions. This set of functions is used to manipulate and monitor a list of circuits. X25lookinit initializes the list, X25lookadd and X25lookdel manipulate list entries, X25looksel queries the list for available data packets and X25lookclose frees the list.

X.25 Function Library

General Functions

• X.25 Operation Functions
• Network Lookup Functions
• Host Lookup Functions
• Miscellaneous Functions
• Macros

X.25 Operation Functions:

X25accept

Accept Call Acceptance

X25clear

Clears any type of call

X25close

Close X.25 connection

X25getcall

Accept an X.25 call

X25incall

Receive an X.25 call

X25interrupt

Send an INTERRUPT

X25interruptconf

Send an INTERRUPT Confirm

X25listen

Listen to Specific Events

X25look

Check for an incoming event

X25makecall

Make an X.25 call

X25open

Open X.25 connection

X25pvcattach

Attach to a PVC

X25pvcdetach

Detach from a PVC

X25hdlcattach

Attach to a HDLC link

X25hdlcdetach

Detach from a HDLC link

X25gotreset

Complete a non-blocking X25pvcattach.

X25read

Read data

X25reset

Send a RESET

X25resetconf

Send a RESET Confirm

X25stoplisten

Stop listening to events

X25write

Write data

Host Lookup Functions:

These function are used to access the host file using the x25hostent structure.

X25endhostent

Stop Host file lookup operations

X25gethostbyaddr

Lookup Host by Address

X25gethostbyname

Lookup Host by Name

X25gethostent

Get host entry

X25sethostent

Start Host file lookup operations

Network Lookup Functions:

These function are used to access the networks database using the x25netent structure.

X25endnetent

End Network Lookup Operations

X25getnetbyboard

Lookup Network By Board and Link No.

X25getnetbyname

Lookup Network by Name

X25getnetbynetid

Lookup Network by Network ID

X25getnetent

Obtain Network Entry

X25setnetent

Start Network Lookup Operations

X25setfilter

Sets the Network type filter for the Network Lookup Functions.

Miscellaneous Functions:

findtag

Find Tag given Tag list

X25error

Print X.25 Error Information

X25errormsg

Print X.25 Error Information into buffer

X25getinfo

Obtain Information from connection

X25getinfotags

Obtain Information from connection

X25getopts

Obtain Global Tags

X25initcps

Initialize cps structure

X25initcpstags

Initialize cps structure

X25initpvc

Initialize _pvcdesc structure

X25initpvctags

Initialize _pvcdesc structure

X25setopts

Set Global Tags

Windows NT only functions

X25linkup

Return the status of the X.25 link

X25lookatone

Check readability of one CALLT

X25lookinit

Initialize the selection list

X25looksel

Check for datagrams on multiple VCs

X25lookadd

Add a CALLT to the selection list

X25lookdel

Remove a CALLT to the selection list

X25lookclose

Close/Free the selection list

X25geterror

Get the library internal error code

X25getsyserror

Obtain system error code

X25seterror

Set the library internal error code

X25setuservalue

Set the value associated with a CALLT

X25getuservalue

Get the value associated with a CALLT

Macros:

ct is of type CALLT *

X25_CPS(ct)

pointer to cps associated with ct

X25_DEVNAME(ct)

device name for this call

X25_FD(ct)

file descriptor for CALLT

X25_ISHDLC(ct)

Is it an HDLC connection?

X25_ISINIT(ct)

Is the CALLT structure initialized?

X25_ISPVC(ct)

Is it a PVC connection?

X25_LCI(ct)

Logical Channel ID

X25_NETID(ct)

Network ID for this call

X25_PVC(ct)

pointer to _pvcdesc associated with ct

Example Program

/***********************************************************************
 *  Module Name: libtest.c
 *
 *  Description:
 *   Sends a string 100 times over an X.25 link
 ***********************************************************************/

#include <stdio.h>
#include <libx25.h>

#define NUMPACKETS     100

main(int argc, char **argv)
{
     CALLT *ct;
     int i, netid = 0;
     char *string = "This is the string being sent across X.25";
     char buf[80];

     if (argc > 1)
        netid = atoi(argv[1]);

     /*
      * Prior to any X.25 activity, obtain a handle for operating
      * the virtual circuit.
      */
     if (!(ct = X25open(netid, TAG_END)))
     {
        X25error("test");
        exit(1);
     }

     /*
      * Make a call to a remote machine at 123456 by sending out a Call
      * Request Packet.
      */
     if (X25makecall(ct, T_OUTPKTSIZE, 256,
                T_DNA, "123456",
                T_CUD, "\01\00\00\00C",
                T_CUDLEN, 5,
                T_VERBOSE, TRUE,
                TAG_END) < 0)
     {
        X25error("test");
        X25close(ct);
        exit(1);
     }

     /*
      * Send the same string to the machine 100 times prepended by
      * it's sequence number.
      */
     for (i = 0; i < NUMPACKETS; i ++)
     {
        sprintf(buf, "%03d: %s\n", i, string);
        if (X25write(ct, T_BUFFER, buf,
                        T_BUFLEN, strlen(buf),
                        TAG_END) < 0)
        {
            X25error("test");
            break;
        }
     }

     /*
      * Now we're done with X.25. Close and exit.
      */
     X25close(ct);
     exit(0);
}

Error Codes

The following is a list of error codes which x25errno can take. If x25errno is set to X25SYSERR check errno for more details. X25error() will print out the error message associated with both X.25 library errors and system errors. Output will be written to the file associated with the X25OUTERR tag FILE pointer. This value defaults to stderr.

X25CLEAR	Call Cleared. Check x25errbuf->cause and x25errbuf->diag for cause and diagnostic codes respectively.
X25NOADDR	No data network address (DNA) given in call to X25makecall()
X25SYSERR	System Error. Error codes depend on operating system.
X25BADMSG	Bad/Undefined Message
X25BADERRMSG	Unknown Error was detected
X25OUTSTATE	Invalid Protocol State
X25USERDATA	User Data Too Large
X25OPTERR	Invalid Tag was passed to a library function.
X25PVCINUSE	PVC in Use
X25NOTAPVC	Not a PVC
X25ISAPVC	Not a valid function for a PVC
X25NOTLISTENER	Not a listening VC
X25BADPID	Bad Protocol ID specification
X25BADDEFAULT	Bad Default listener
X25RESET	Call Reset. Check x25errbuf->cause and x25errbuf->diag for cause and diagnostic codes respectively.
X25INTRCONF	Interrupt Confirmation
X25INTERRUPT	Interrupt
X25FILEFMT	Bad File Format in x25hosts or packetnets database
X25DATAIND	Data Indication. Incoming data is waiting.
X25DATAACKIND	Data Ack. Indication
X25RESETCOMP	Reset Completed
X25CALLIND	Call Indication use X25getcall() to establish a connection
X25CONNECTEDIND	Call Connected Indication. Connection has been established.
X25BADNUI	Bad NUI Syntax
X25FACLEN	Facility String Too Long
X25PVCSYN	Syntax Error in PVC String
X25BADNULL	Bad Null-protocol Listener
X25HDLCSYN	Syntax Error in HDLC String
X25BADCALLT	Bad CALLT contents
X25NOVC	No VC Specified in X25getcall()
X25NOTINIT	Call Not Initialized Properly
X25BADBUFFER	Bad Buffer Specification (ie. NULL pointer or zero sized buffer)
X25BADNETID	Unable to Look up Network ID
X25NOTFOUND	File not found ie. x25hosts.
X25BADDNA	Bad Data Network Address (DNA pointer is NULL or the size is greater than CPS_ADDMAX)
X25BADCUD	Bad Call User Data (CUD pointer is NULL or the size is greater than CPS_CCUDMAX)
X25BADHOST	Bad Host Name or Address (unable to look up host or address in x25hosts

Supported Tags

This is a list of currently supported tags and an explanation of their meanings. Global tags can be used by any function expecting tag arguments, while specialized tags can only be used by specific functions.

Note that the expected data type of the tag argument (the next argument passed to a library function) differs from tag to tag; it may even differ for a given type of tag, depending on which library function the tag is passed to. In general, when passing a tag to X25getinfo() to obtain an X.25 setting, the tag argument must be a pointer to the memory location where you would like to store the data. So if the data is an integer, the tag argument will be a pointer to an integer (int *); if the data is already a pointer, the tag argument will be a pointer to a pointer, etc.

Special tags

TAG_IGNORE	Ignore this tag and its argument
TAG_END	End of Tag List
TAG_DONE	Synonym for TAG_END
T_END	Another Synonym for TAG_END

Global Tags:

T_OUTERR	A file stream where X.25 error messages will be sent by X25error() and other library functions if verbose mode is turned on. The present error output stream is stored in the global variable x25outerr, and is stdout by default. Pass a value of type (FILE *) when setting the error output stream; pass a value of type (FILE **) when obtaining it.
T_VERBOSE	A boolean telling the library whether to comment on the progress of X.25 functions by printing out status messages to the error output stream. The present verbose mode is stored in the global variable x25verbose, and is FALSE by default. Pass a value of type (int), where zero indicates FALSE and non-zero TRUE, when setting the verbose mode; pass a value of type (int *) when obtaining it. This tag is ignored under Windows NT.
T_BLOCKING	A boolean that determines whether to block (wait) on library calls or not. For example, when X25read() is used with blocking on, the library will wait until a packet is read or a predetermined length of time has elapsed; otherwise it will fail immediately if no packet is ready. The blocking mode is stored in the global variable x25blocking, and is TRUE by default. Pass a value of type (int), where zero indicates FALSE and non-zero TRUE, when setting the blocking mode; pass a value of type (int *) when obtaining it. This tag is not yet available under Windows NT.
T_TIMEOUT	The number of seconds to block before returning unsuccessfully. The present timeout delay is stored in the global variable x25timeout, and is 60 by default. Pass a value of type (int) when setting the timeout delay; pass pass a value of type (int *) when obtaining it. This tag is not yet available under Windows NT.

Specialized Tags

T_DEVICE	Device name string from the packetnets database. Pass a value of type (char *) when specifying the device name.
T_BOARD	Board number of the X.25 card to use, starting at zero for the first card installed in the system. Pass a value of type (int) when specifying the board number.
T_LINK	Link number to use, starting at zero for the first link on the X.25 card. Pass a value of type (int) when specifying the link number.
T_OUTPKTSIZE	Maximum data packet size for outgoing packets, in bytes. Pass a value of type (int) when setting the outgoing packet size; pass a value of type (int *) when obtaining it.
T_INPKTSIZE	Maximum data packet size for incoming packets, in bytes. Pass a value of type (int) when setting the incoming packet size; pass a value of type (int *) when obtaining it.
T_PKTSIZE	Used to set both in ingoing and outgoing packet sizes to the same value. If these sizes are to be different, you must use T_OUTPKTSIZE and T_INPKTSIZE separately.
T_DNA	Pointer to remote Data Network Address buffer, used in conjunction with the T_DNALEN tag. Pass a value of type (char *) when setting the remote DNA; pass a value of type (char **) when obtaining it.
T_DNALEN	Length of Data Network Address string (in bytes), used in conjunction with the T_DNA tag. Pass a value of type (int) when specifying the DNA length; pass a value of type (int *) when obtaining it.
T_CUD	Pointer to Call User Data buffer, used in conjunction with the T_CUDLEN tag. This buffer contains any data you wish to pass when making a call. Pass a value of type (char *) when setting the CUD for an outgoing call; pass a value of type (char **) when obtaining the CUD of an established call.
T_CUDLEN	Length of Call User Data buffer, used in conjunction with the T_CUD tag. Pass a value of type (int) when specifying the length of the CUD buffer; pass a value of type (int *) when obtaining it.
T_BUFFER	Pointer to a user-allocated buffer, used in conjunction with the T_BUFLEN tag. Pass a value of type (char *) when providing a buffer to any library function.
T_BUFLEN	Size of a user-allocated buffer, used in conjunction with the T_BUFFER tag. Pass a value of type (int) when specifying the buffer size.
T_PRIORITYCALL	Priority service flag (Datapac). Pass a value of type (int), where zero is FALSE and non-zero is TRUE, when setting the priority flag; pass a value of type (int *) when obtaining it.
T_REVERSE	Reverse Charge flag, used to indicate that the end accepting an X.25 call will be charged for its cost, rather than the end making the call. Pass a value of type (int), where zero is FALSE and non-zero is TRUE, when setting the reverse charge flag; pass a value of type (int *) when obtaining it.
T_BITS	Bitfield comprised of some combination of QBIT, DBIT, and MBIT 'or'ed together. Pass a value of type (int) when setting the bitfield for an outgoing packet; pass a value of type (int *) when obtaining it for an incoming packet.
T_OUTWINDOW	Outgoing window size, the number of outgoing frames that can be queued before flow control occurs. Pass a value of type (int) when setting the outgoing window size; pass a value of type (int *) when obtaining it.
T_INWINDOW	Incoming window size, the number of incoming frames that can be queued before flow control occurs. Pass a value of type (int) when setting the incoming window size; pass a value of type (int *) when obtaining it.
T_WINDOW	Used to set both in ingoing and outgoing window sizes to the same value. If these sizes are to be different, you must use T_OUTWINDOW and T_INWINDOW separately.
T_OUTTHRUCLASS	Outgoing throughput class, a number from 3 to 12 representing bits per second. Pass a value of type (int) when specifying the throughput class; pass a value of type (int *) when obtaining it.
T_INTHRUCLASS	Incoming throughput class, a number from 3 to 12 representing bits per second. Pass a value of type (int) when specifying the throughput class; pass a value of type (int *) when obtaining it.
T_THRUCLASS	Used to set both in ingoing and outgoing throughput classes to the same value. If these classes are to be different, you must use T_OUTTHRUCLASS and T_INTHRUCLASS separately.
T_LCI	Used to specify the Logical Channel Identifier number when establishing a PVC connection. Pass a value of type (int) when setting the LCI.
T_CALLINDEX	Used to specify the call index of an incoming call. Pass a value of type (int) when specifying the call index.
T_CPSP	Pointer to a fully qualified CPS stucture, which contains connection parameters for SVCs. This tag is useful for setting or obtaining many parameters at once. Pass a value of type (cps *).
T_PVCP	Pointer to a fully qualified _pvcdesc stucture, which contains connection parameters for PVCs. This tag is useful for setting or obtaining many parameters at once. Pass a value of type (_pvcdesc *).
T_CAUSE	Cause code for a clear or reset. See the Administrator's Guide for a complete list of cause codes. Pass a value of type (int) when setting the cause code.
T_XIPCAUSE	XIP cause code for a clear or reset. See the Administrator's Guide for a complete list of XIP cause codes. Pass a value of type (int) when setting the XIP cause code.
T_DIAG	Diagnostic code for a clear or reset. See the Administrator's Guide for a complete list of diagnostic codes. Pass a value of type (int) when setting the diagnostic code.
T_NETNAME	Network name string from the packetnets database. Pass a value of type (char *) when specifying the network name.
T_LISTENTYPE	Type of liston to perform; see X25listen() for details. Pass a value of type (int) when specifying the listen type.
T_NUMLISTEN	Number of elements in an array protocol identifiers, used in conjunction with the T_LISTENPIDS tag. Pass a value of type (int) when specifying the array size.
T_LISTENPIDS	Pointer to an array of protocol identifiers, which each correspond to the first character in a CUD string. Pass a value of type (int *) when specifying the array of protocol IDs.
T_NUI	Network user ID string, used only when making or accepting a call. Pass a value of type (char *) when specifying the NUI; pass a value of type (char **) when obtaining it.
T_NUILEN	Length of network user ID buffer, used in conjunction with the T_CUD tag. Pass a value of type (int) when specifying the length of the CUD buffer; pass a value of type (int *) when obtaining it.
T_FLAGS	Flags to pass to an open() system call when first calling X25open(). Pass a value of type (int) when specifying the flags.
T_DBITSUPPORT	DBIT flag, used to request that end-to-end Data Ack packets be transmitted. Pass a value of type (int), a boolean where zero is FALSE and non-zero is TRUE.
T_HOST	Remote host name string from the x25hosts file. Pass a value of type (int *) when specifying the host name.
T_HOSTADDR	Remote host address string from the x25hosts file. Pass a value of type (int *) when specifying the host name.
T_NOWAIT	No-wait flag. If FALSE (zero), wait to receive a Call Accept message when making a call; if TRUE (non-zero), do not wait. Pass a value of type (int) when specifying the no-wait flag.
T_PNETID	A pointer to an integer which is to contain the Network ID.

[ Functions | Contents | Tags | Errors ]

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25accept(CALLT *ct)

Description:

This function will process Call acceptance of a previous X25makecall() with the T_NOWAIT tag set to TRUE.
This function assumes that there is a call acceptance packet to be read. (ie. X25look() returns X25CONNECTEDIND).

Arguments:

ct - pointer to CALLT structure

Returns:

0 on success

-1 on failure

See Also:

X25makecall

X25look

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25clear(CALLT *ct, TAG LIST)

X25cleartags(CALLT *ct, tags);

Description:

Clears an X.25 call. Not valid on PVCs. There are 3 ways to call this function:

• No tags (except TAG_END of course!) In this case the driver will use a Diagnostic and XIP cause of XCA_CLOSED, and a Cause value of 0x00
• You may supply the cps structure (using T_CPSP) in which case all the other tags are not considered. you may use the value NULL for this tag in order to use the cps associated with this call. If you are using this tag then the other tags will have no effect
• You may supply the Cause value (T_CAUSE) (defaults to 0x00) you may also supply a diagnostic (T_DIAG) (defaults to XCA_CLOSED) you may also supply an XIP Cause code (T_XIPCAUSE) (def. to 0x00)

Tags recognized:

All global tags

T_DIAG

T_CAUSE

T_XIPCAUSE

T_CPSP

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

0 for success

-1 for failure

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25close(CALLT *ct)

Description:

Closes the file descriptor associated with a specific call Frees all internally allocated memory for a specific call. Calls X25pvcdetach() for PVCs or X25clear() if a call was established. After this call ct should no longer be considered a valid pointer and X25_FD() will no longer return a valid file descriptor.

Arguments:

ct - pointer to CALLT structure

Returns:

None

See Also:

X25open

X25clear

X25pvcdetach

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25error(char *string)

Description:

Prints the error message associated with X.25 library error codes as in perror(S). If a system error was encountered it will also be printed. The resulting output will be of the form: string: error message In the case of a Clear or Reset, the cause and diagnostic codes are also printed. This function will reset the library error codes.

Arguments:

string - pointer to message to print

Returns:

none

See Also:

X25errormsg

X25geterror

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25errormsg(int xerrno, char *buf, int buflen)

Description:

Prints the error message associated with X.25 library error codes into the buffer pointed to by buf. It returns the number of characters copied into buf or the number of characters needed to copy the resulting string if buflen is too small.

Arguments:

xerrno - X.25 Error Number

buf - buffer to copy into

buflen - length of buffer

Returns:

number of characters copied or needed

See Also:

X25error

X25geterror

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25getinfo(CALLT *ct, TAG LIST)

X25getinfotags(CALLT *ct, TAGS *tags)

Description:

Obtains information from an established call for both PVCs and SVCs. NOTE: Tags expect pointers to valid areas of memory as arguments

Example:

int size; CALLT *ct;

rc = X25getinfo(ct, T_OUTPKTSIZE, &size, TAG_END);

Tags recognized:

All global tags

T_INPKTSIZE

T_OUTPKTSIZE

T_INWINDOW

T_OUTWINDOW

T_PRIORITYCALL

T_REVERSE

T_CUD

T_CUDLEN

T_DNA

T_DNALEN

T_LCI

T_NUI

T_NUILEN

T_INTHRUCLASS

T_OUTTHRUCLASS

T_CPSP

T_PVCP

T_DBITSUPPORT

Arguments:

CALLT *ct - pointer to callt structure to initialize

TAGS *tags - pointer to tag list containg options

Returns:

0 For success

-1 For error

See Also:

X25makecall

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25getcall(CALLT *ct, TAG LIST)

X25getcalltags(CALLT *ct, TAGS *tags)

Description:

X25getcall() will accept a call. The cps for this call will be updated. The T_CALLINDEX argument MUST be specified and can be obtained by the user program from the x25daemon by specifying $index on the x25incalls or x25tab command line or by calling X25incall().

Tags recognized:

All global tags, T_CALLINDEX

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

0 on success

-1 on failure

See Also:

X25incall

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25getopts(0, TAG LIST)

X25getoptstags(TAGS *tags)

Description:

Obtains the value of global X.25 library parameters

Arguments:

tags - pointer to TAGS list containing pointer to variables to hold information requested.

Tags recognized:

T_OUTERR

T_TIMEOUT

T_VERBOSE

Returns:

None

See Also:

X25setopts

[ Functions | Contents | Tags | Errors ]

See X25pvcattach

[ Functions | Contents | Tags | Errors ]

See X25pvcdetach

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25incall(CALLT *ct, TAG LIST)

X25incalltags(CALLT *ct, TAGS *tags)

Description:

X25incall() will receive a call index for a pending incoming call. This call index is appropriate to use for a call to X25getcall(). This function should be called with the ct associated with the X25listen() request. Normally this function is used after establishing that a call has indeed been received using the X25look() function. The T_PNETID allows determining on which netid the call arrived on. The T_CPSP tag with a pointer to enough storage for a cps structure will copy the cps (Call Progress Structure) into that user supplied buffer.

Tags recognized:

T_PNETID

T_CPSP

All global tags

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

call index on success

-1 on failure

See Also:

X25incall

X25getcall

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25initcps(cps *cpsp)

Description:

Clear cps structure, thereby allowing the drivers to use their default values.

Arguments:

cpsp - pointer to cps structure to initialize

Returns:

None

See Also:

X25initcpstags

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25initcpstags(cps *cpsp, TAGS *tags)

Description:

Initializes cps with the information contained in tags This function is usually not required to be called directly unless you are using your own cps structure.

Note: To specify the DNA you need not provide the T_DNALEN tag. If this T_DNALEN is not provided it will assume to take the length of the string passed to T_DNA. The T_CUD and T_NUI tags, however, require the presence of T_CUDLEN and T_NUILEN respectively. The tags T_PKTSIZE, T_WINDOW, T_THRUCLASS may be used to specify both incoming and outgoing values. If T_INx is specified and T_OUTx is not specified, the value for T_OUTx is set to the same as specified for T_INx. If T_OUTx is specified and T_INx is not specified, the value for T_INx is set to the same as specified for T_OUTx.

Tags recognized:

All global tags

T_PKTSIZE

T_INPKTSIZE

T_OUTPKTSIZE

T_WINDOW

T_INWINDOW

T_OUTWINDOW

T_PRIORITYCALL

T_REVERSE

T_CUD

T_CUDLEN

T_DNA

T_DNALEN

T_NUI

T_NUILEN

T_THRUCLASS

T_INTHRUCLASS

T_OUTTHRUCLASS

T_CPSP

T_PVCP

T_DBITSUPPORT

Arguments:

cps *cpsp - pointer to cps structure to initialize

TAGS *tags - pointer to tag list containg options

Returns:

0 on Success

-1 on Error

See Also:

X25initcps

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25initpvc(_pvcdesc *pvcp)

Description:

Initialize _pvcdesc structure to default values of all zeroes, which implies that the Packet Level or SPI drivers will use the configured defaults. However the default LCI number is still set to 1.

Arguments:

pvcp - pointer to _pvcdesc structure to initialize

Returns:

None

See Also:

X25initpvctags

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25initpvctags(_pvcdesc *pvcp, TAGS *tags)

Description:

Initializes pvc with the information contained in tags

Tags recognized:

All global tags

T_PKTSIZE

T_INPKTSIZE

T_OUTPKTSIZE

T_WINDOW

T_INWINDOW

T_OUTWINDOW

T_LCI

Arguments:

pvcp - pointer to _pvcdesc structure to initialize

tags - pointer to TAGS list

Returns:

0 on Success

-1 on Error

See Also:

X25initpvc

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25interrupt(CALLT *ct, TAG LIST)

X25interrupttags(CALLT *ct, TAGS *tags)

Description:

Send an INTERRUPT with given buffer specified by T_BUFFER and T_BUFLEN.

Tags recognized:

All global tags

T_BUFFER

T_BUFLEN

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

0 on success

-1 on failure

See Also:

X25interruptconf

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25interruptconf(CALLT *ct)

Description:

Send an INTERRUPT CONFIRM.

Arguments:

ct - pointer to CALLT structure

Returns:

0 on success

-1 on failure

See Also:

X25interrupt

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25listen(CALLT *ct, TAG LIST);

X25listentags(CALLT *ct, TAGS *tags)

Description:

This function will initiate a listen request for the specified protocol identifier which is the first byte of Call User Data. This is usually Hex 01 for CCITT X.29 calls. Valid values for the T_LISTENTYPE tag are:

X25_LISTEN_DEF

default listener

X25_LISTEN_NULL

Null listener

X25_LISTEN_ACC

Accounting information

Tags recognized:

All global tags

T_LISTENTYPE

T_NUMLISTEN

T_LISTENPIDS

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

0 on success

-1 on failure

See Also:

X25getcall

X25stoplisten

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25look(CALLT *ct)

Description:

This function should be used to see if there are any events ready to be read.

This function is not available under Windows NT. Please see X25looksel()

X25look() returns one of the following event codes:

X25CLEAR

The call was cleared

X25SYSERR

System Error Message

X25BADMSG

Unexpected Message from Driver

X25BADERRMSG

Unknown Error Message

X25OUTSTATE

Message Received Out of State

X25RESET

Received Reset

X25INTRCONF

Received Interrupt Confirm

X25INTERRUPT

Received Interrupt

X25DATAIND

Received Data

X25DATAACKIND

Received Data Ack

X25RESETCOMP

Received Reset Complete

X25CALLIND

Received Call Indication

X25CONNECTEDIND

Received Call Connected Indication

Arguments:

ct - pointer to CALLT

Returns:

0 if nothing unusual occurred.

Error Code or -1 (Error code also set in x25errno)

See Also:

X25looksel

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25makecall(CALLT *ct, TAG LIST)

X25makecalltags(CALLT *ct, TAGS *tags)

Description:

Makes an X.25 call and waits for call acceptance. There are two ways to specify parameters to this function. The first involves passing in each parameter seperately, however, for the advanced user, a cps may be passed in directly using the T_CPSP tag. The T_HOST tag will use the host names in the x25hosts file to bind default options to a particular host. T_HOSTADDR will try to match a host by it's address from the x25hosts file.
T_DNA will default to 9999 if not supplied.
T_CUD will default to 1 0 0 0 if not supplied.

Tags recognized:

All global tags

T_INPKTSIZE

T_OUTPKTSIZE

T_INWINDOW

T_OUTWINDOW

T_PRIORITYCALL

T_REVERSE

T_CUD

T_CUDLEN

T_DNA

T_DNALEN

T_NUI

T_CPSP

T_NUILEN

T_INTHRUCLASS

T_OUTTHRUCLASS

T_DBITSUPPORT

T_PKTSIZE

T_WINDOW

T_THRUCLASS

T_HOST

T_HOSTADDR

T_NOWAIT

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

0 on success

-1 on failure

See Also:

x25hosts

Possible Error Codes

X25SYSERR	Unable to allocate memory for internal operations
X25PVCINUSE	CALLT already in use as a PVC
X25BADCALLT	*ct passed addresses an invalid CALLT, or one already in use
X25BADMSG	Internal Error: unrecognizable message from Driver
X25CLEAR	X.25 call not connected. Check x25errbuf for clearing codes.
X25CONNECTEDIND	Not an error: Call connected
X25BADCUD	Call user Data Length of 0 not allowed
X25BADDNA	Data network address either 0 or too large
X25BADHOST	Unable to look up host name or address in x25hosts file>
X25BADNUI	Bad NUI syntax

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25open(int netid, TAG LIST)

X25opentags(int netid, TAGS *tags)

Description:<

X25open opens a suitable X.25 device and sets up the user's context. No calls are made or accepted. You may use the T_FLAGS tag to specify special options for the open() flag.
The macro X25_FD() is valid after a call to this function. The T_BLOCKING tag set to FALSE, will set non-blocking mode on the associated file descriptor.

You may call this function in 4 ways:

• Specify a valid network ID as the first argument
• Specify a valid network name (T_NETNAME)
• Specify a valid board and link (T_BOARD, T_LINK) - Not recommended!
• Specify a device name (T_DEVNAME) - Not recommended!

Tags recognized:

All global tags

T_DEVICE

T_NETNAME

T_FLAGS

T_BOARD

T_LINK

T_BLOCKING

Arguments:

netid - network ID to open (ignored depending on tag choices)

tags - pointer to TAGS list

Returns:

pointer to a CALLT structure on success

NULL on failure

See Also:

X25close

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25pvcattach(CALLT *ct, TAG LIST)

X25hdlcattach(CALLT *ct, TAG LIST) Defined

X25pvcattachtags(CALLT *ct, TAGS *tags)

Description:

This function tries to establish a PVC or HDLC connection over the given Logical Channel (defaults to 1). The T_NOWAIT call allows the operation of this function to be split as to not block. By default X25pvcattach sends out a RESET. It waits for a RESET from the other side and sends out a RESET confirm. By specifying the T_NOWAIT tag, X25pvcattach does not wait for the remote initiated RESET. However, on detecting a RESET ( (by using a look function for example) you must call the X25gotreset function.

Tags recognized:

All global tags

T_OUTPKTSIZE

T_INPKTSIZE

T_INWINDOW

T_OUTWINDOW

T_PKTSIZE

T_WINDOW

T_LCI

T_PVCP

T_NOWAIT

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

0 on success

-1 on failure

See Also:

X25pvcdetach

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25gotreset(CALLT *ct, TAG LIST)

X25gotresettags(CALLT *ct, TAGS *tags)

Description:

This function validates the state of ct (returning -1 if not appropriate) It then sends out a RESET CONFIRM. Use this function only after calling X25pvcattach with the T_NOWAIT tag.

Tags recognized:

None

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

0 on success

-1 on failure

See Also:

X25pvcattach

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25pvcdetach(CALLT *ct, TAG LIST)

X25hdlcdetach(CALLT *ct, TAG LIST) Defined

X25pvcdetachtags(CALLT *ct, TAGS *tags)

Description:

Detaches from PVC or HDLC associated with ct.

Tags recognized:

None

Arguments:

ct - pointer to CALLT structure

tags - pointer to tags list

Returns:

0 on success

-1 on failure

See Also:

X25pvcattach

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25read(CALLT *ct, TAG LIST);

X25readtags(CALLT *ct, TAGS *tags)

Description:

Receive characters from an X.25 connection. You may use this function to receive data from SVC or PVC connections. This function returns the number of bytes read. The function expects a buffer big enough to hold the largest packet. If the packet is larger than the buffer, this buffer is returned full, and the next X25read will return the next bytes of the packet. It is a good idea to check the x25errno variable for more information when a -1 is returned. To check for System interrupts ie. EINTR check if x25errno == X25SYSERR and errno == EINTR.

NOTE: the T_BITS tag expects a pointer to an integer which is to hold a combination of DBIT, and QBIT. The M Bit should never be set.

When receiving a packet with the D Bit set, X25read will send an acknowledgement.

The T_BLOCKING and T_TIMEOUT tags available under UNIX are not available under NT. To avoid waiting for data under NT, see the Frame Reception Overview discussion.

Tags recognized:

All global tags

T_BUFFER

T_BUFLEN

T_BITS

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

The number of characters read on success

-1 on failure

Possible Error Codes:

X25SYSERR

X25CLEAR

X25RESET

X25BADBUFFER

X25NOTINIT

X25BADCALLT

See Also:

X25write

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25write(CALLT *ct, TAG LIST)

X25writetags(CALLT *ct, TAGS *tags);

Description:

Send data over an established X.25 connection. You may use this function to send data over SVC or PVC connections. This function returns the number of bytes written and it is the user's responsibility to handle the condition in which this count does not equal the buffer length. A good way to accomplish this would be to look at the x25errno global variable and decide on a proper action.

NOTE: the T_BITS tag expects an integer containing some combination of DBIT, MBIT & QBIT

If D Bit acknowledgement is active, then for each call to this function an X25read() should be performed which will return an X25DATAACK status code.

Tags recognized:

All global tags

T_BITS

T_BUFFER

T_BUFLEN

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

Number of bytes written when successful.

-1 on failure

Possible Error Codes:

X25SYSERR

X25CLEAR

X25RESET

X25BADBUFFER

X25NOTINIT

X25BADCALLT

See Also:

X25read

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25linkup(CALLT *ct)

Windows NT ONLY!

Description:

Check if the X.25 link is up.
This function returns the status of the X.25 link associated with ct.

Arguments:

ct - pointer to CALLT structure

Returns:

0 - if the link is down

1 - if the link is up

-1 on failure

Possible Error Codes:

X25SYSERR

X25BADCALLT

See Also:

X25open

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25reset(CALLT *ct, TAG LIST)

X25resettags(CALLT *ct, TAGS *tags)

Description:

Send a RESET with given cause and diagnostic values specified by the T_CAUSE and T_DIAG tags respectively.

Tags recognized:

All global tags

T_CAUSE

T_DIAG

Arguments:

ct - pointer to CALLT structure

tags - pointer to TAGS list

Returns:

0 on success

-1 on failure

Possible Error Codes:

X25SYSERR

X25BADCALLT

See Also:

X25resetconf

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25resetconf(CALLT *ct)

Description:

Send a RESET Confirm.

Arguments:

ct - pointer to CALLT structure

Returns:

0 on success

-1 on failure

Possible Error Codes:

X25NOTINIT

X25BADCALLT

See Also:

X25reset

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25stoplisten(CALLT *ct);

Description:

This function will stop a listen request

Arguments:

ct - pointer to CALLT structure

Returns:

0 on success

-1 on failure

Possible Error Codes:

X25SYSERR

X25BADCALLT

See Also:

X25listen

[ Functions | Contents | Tags | Errors ]

Function Prototype:

findtag(TAGS *tags, unsigned long item)

Description:

Finds the tag item in the tags array pointed to by tags.

Arguments:

tags - pointer to TAGS list

item - item to find in tags

Returns:

Index of the required tag item in the tags list

-1 if not found.

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25setopts(0, TAG LIST)

X25setoptstags(TAGS *tags)

Description:

Sets global X.25 library parameters

Tags recognized:

T_OUTERR

T_TIMEOUT

T_VERBOSE

Arguments:

tags - pointer to TAGS list

Returns:

None

See Also:

X25getopts

[ Functions | Contents | Tags | Errors ]

Under Windows NT network database information is stored in the registry under the key: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\wanlog\Parameters.

Unix based implementations have a file which lives in /etc.

Example of a UNIX packetnets file:

###########################################################################
#
#   General format for this file
#   NETID x
#       <one or more of the following tags>
#       <action list>
#   END
#
#       Tag             Description
#       =======         =============
#       TYPE            Network type (ie. X25, FREL, etc.)
#       BOARD           Board number
#       LINK            Link number
#       NAME            Network Name (ie. link0)
#       NETWORK         Network Layer (ie. /dev/x25pkt)
#       CONFIG          Name of configuration file
#
#       Actions         Description
#       ==========      =============
#       OPEN            Open device /dev/x25hpx
#       ATTACH          Send dl_attach with a given PPA
#       PUSH            Push a module
#       LINK            Open and link
#       SETNID          Set Network ID
#       SETCONF         Set Configuration (N/A)
#       DLPI            DLPI conversion module pushed
#       ENABLERX        Enable Receiver
#       PDK             PDK stack
#
#########################################################################

NETID   0
        NAME    link00
        TYPE    X25
        CONFIG  net.default
        BOARD   0
        LINK    0
        NETWORK /dev/x25spi
        SETCONF
END

NETID   1
        NAME    link01
        TYPE    X25
        CONFIG  net.default
        BOARD   0
        LINK    1
        NETWORK /dev/x25spi
        SETCONF
END

[ Functions | Contents | Tags | Errors ]

The x25netent structure contains information on the attached links which are useable for X.25 or Frame Relay operation. Each entry specifies the network ID by which this link is known by, its network name, as well as board mappings used by some applications. The device name used to access this device is also available.

All network file access functions will return a pointer to a static area which will be overwritten by the next call to a network file access function.

See libx25.h for the full definition of the x25netent structure.

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25setnetent(void)

Description:

Initializes the X.25 networks database for reading. The first X25getnetent() will return the first network in the file. Subsequent calls to this function will rewind the file pointer to the beginning of the file. The function X25endnetent() should be called to terminate network file processing.

Arguments:

None

Returns:

None

See Also:

X25endnetent

X25getnetent

X25setfilter

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25endnetent(void)

Description:

Ends network database operations.

Arguments:

None

Returns:

none

See Also:

X25setnetent

X25getnetent

X25setfilter

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25getnetent(void)

Description:

Obtains one struct x25netent entry from the networks database Each call to this function will retrieve the next network entry in this file in the form of an x25netent structure.

Arguments:

None

Returns:

pointer to struct x25netent on success

NULL on failure

See Also:

X25setnetent

X25endnetent

X25setfilter

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25getnetbyname(char *name)

Description:

Looks up a network entry given a network name from the networks database. There is no need to call X25setnetent() or X25endnetent() before and after calling this function. This function will return a pointer to an x25netent structure.

Arguments:

name - Network name to find

Returns:

pointer to struct x25netent on success

NULL on failure

See Also:

X25getnetbynetid

X25setfilter

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25getnetbynetid(int netid)

Description:

Looks up a network entry given a network ID from the networks database. There is no need to call X25setnetent() or X25endnetent() before and after calling this function. This function will return a pointer to an x25netent structure.

Arguments:

netid - Network ID to find

Returns:

pointer to struct x25netent on success

NULL on failure

See Also:

X25getnetbyname

X25setfilter

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25getnetbyboard(int board, int link)

Description:

Looks up a network entry given a board and link number from the networks database. This function is provided to ease migration to the network ID scheme of naming eligible links. If at all possible use the Network ID or Name to resolve links. There is no need to call X25setnetent() or X25endnetent() before and after calling this function. This function will return a pointer to an x25netent structure.

Arguments:

board - Board number

link - Link number

Returns:

pointer to struct x25netent on success

NULL on failure

See Also:

X25getnetbyname

X25getnetbynetid

X25setfilter

Function Prototype:

void X25setfilter(int typemask)

Description:

Sets a network type filter for all accesses to the packetnets database so that the functions X25getnetent(), X25getnetby...() will return only the specified network types. The default type for the X25getnet..() functions is NETX25_TYPE. X25open resets the default type to NETX25_TYPE.

Arguments:

typemask - Mask for Network types. ie. NETFREL_TYPE | NETX25_TYPE
NETALL_TYPE will select all network types.

Returns:

NONE

See Also:

X25getnetent

X25getnetbyname

X25getnetbynetid

Function Prototype:

X25sethostent(void)

Description:

Initializes the X.25 hosts file for reading. The first X25gethostent() will return the first host in the file. Subsequent calls to this function will rewind the file pointer to the beginning of the file. Host file processing should be terminated by a call to X25endhostent().

Arguments:

None

Returns:

None

See Also:

X25endhostent

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25endhostent(void)

Description:

Ends hosts file processing, closing the file.

Arguments:

None

Returns:

None

See Also:

X25sethostent

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25gethostent(void)

Description:

Returns next x25hostent structure in the hosts file.

Arguments:

None

Returns:

pointer to struct x25hostent if found

NULL if not found

See Also:

X25sethostent

X25endhostent

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25gethostbyaddr(char *addr)

Description:

Finds host based on X.25 address specified in the hosts file. There is no need to call X25sethostent() or X25endhostent() before and after calling this function. The function returns a pointer to an x25hostent structure.

Arguments:

addr - pointer to DNA address string

Returns:

struct x25hostent pointer if found

NULL if not found

See Also:

X25gethostbyname

[ Functions | Contents | Tags | Errors ]

Function Prototype:

X25gethostbyname(char *name)

Description:

Finds a host in the hosts file based on its name. There is no need to call X25sethostent() or X25endhostent() before and after calling this function. The function returns a pointer to an x25hostent structure.

Arguments:

name - pointer to name string

Returns:

struct x25hostent pointer if found

NULL if not found

See Also:

X25gethostbyaddr

[ Functions | Contents | Tags | Errors ]

Function Prototype:

int X25lookatone(CALLT *ct, int tmout);

Windows NT ONLY!

Description:

Checks if there is a datagram to be read from ct.

Arguments:

ct - CALLT to check

tmout - timeout in millisecs, (0 for non blocking, -1 to block indefinitely)

Returns:

1 - if there something to be read

0 - if there is nothing

See Also:

X25lookinit

X25lookadd

X25lookdel

X25looksel

X25lookclose

Function Prototype:

X25_lookent *X25lookinit(int maxcallt);

Windows NT ONLY!

Description:

Initializes the selection mechanism for file descriptors. Currently the limit for the number of file descriptors to listen on is imposed by the operating system to be 512. If maxcallt is specfied to be more than 512 the function call will succeed, but still only 512 file descriptors are allowed. The pointer returned by this function must be used in all the other "look" functions expecting a X25_lookent.

Arguments:

maxcallt - maximum number of CALLTs (< 512)

Returns:

X25_lookent pointer on success

NULL - on failure (out of memory)

See Also:

X25lookadd

X25lookdel

X25looksel

X25lookclose

Function Prototype:

int X25lookadd(X25_lookent *look, CALLT *ct);

Windows NT ONLY!

Description:

Add the file descriptor associated with ct to the selection list contained in look.

Arguments:

look - pointer to X25_lookent structure

ct - pointer to CALLT to add

Returns:

0 - on success

-1 - on failure

See Also:

X25lookinit

X25lookdel

X25look

X25looksel

X25lookclose

Function Prototype:

int X25lookdel(X25_lookent *look, CALLT *ct);

Windows NT ONLY!

Description:

Remove the file descriptor associated with ct from the selection list contained in look.

Arguments:

look - pointer to X25_lookent structure

ct - pointer to CALLT to delete

Returns:

0 - on success

-1 - on failure

See Also:

X25lookinit

X25lookadd

X25look

X25looksel

X25lookclose

Function Prototype:

CALLT *X25looksel(X25_lookent *look, int tmout);

Windows NT ONLY!

Description:

Checks for availability of datagrams for the DLCIs in the selection list specified through X25lookadd

Arguments:

look - pointer to X25lookent structure

tmout - millisecs to wait (use -1 for infinity, 0 for no wait)

Returns:

ct - pointer to CALLT if there is a datagram to be read on the file descriptor associated with this CALLT

NULL - nothing to read, or timeout

See Also:

X25lookadd

X25lookdel

X25lookclose

Function Prototype:

CALLT *X25lookclose(X25_lookent *look);

Windows NT ONLY!

Description:

Closes the selection mechanism for the "look" functions.

Arguments:

look - pointer to X25_lookent structure

Returns:

NONE

See Also:

X25lookinit

X25lookadd

X25lookdel

X25looksel