Introduction
Compiling
Network Lookup Function Overview
Host Lookup Functions Overview
Packet Reception Status Function
Overview
X.25 Functions
Example Program
Error Handling and Codes
Supported Tags
X.25 Library Header File
x25netent structure
X.25 API Reference
The X.25 library is an abstraction layer which allows programmers to focus on their protocol-sensitive application development, without regard for the mechanisms used to communicate with the X.25 infrastructure. Within limits, the library allows the development of applications which (at the source code level) work on Netcom II, Wanware Linux, Wanware/NT, and the SyncServer product lines.
The library is partly based on a concept called 'Tags'; library routines use Tags to obtain parameters for some functions. Tags are almost always passed in pairs: the manifest constant for the tag itself and the value associated with it. (The only exception to this is the last tag in the list, which must 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);
Any function capable of accepting tag arguments can be called in either of two ways. The first is to pass a variable number of tag arguments This method allows for great flexibility, especially the ability to use C's conditional operator to create conditional tags. Example:
X25clear(ct, diag_known ? T_DIAG : T_IGNORE, 0x80, TAG_END);
The second way involves passing an array of tags, which must still include a TAG_END. This method results in faster execution in most cases, since the library normally converts variable argument tags into an array form before processing them. You may wish to use this method when you are passing the same tags over and over again. Example:
TAGS mytags[] = { {T_DIAG, 0x80}, {TAG_END, 0} };
X25cleartags(ct, mytags);
Most functions will return 0 for success or -1 for failure.
An error code may be retrieved by calling X25geterror() or X25geterrorct() when processing a CALLT. X25error() may be called to print out an explanation for the error on stdout. X25errormsg() may be called to translate the error code into a message. Please see X.25 Library Header File for a list of currently defined error codes.
There are three key points for compiling and linking applications with the X.25 library.
The appropriate define may be done in one of two ways. First, you can define it in each C source file (eg, #define LINUX at the very top of the file). Second, you make this a command line option (C flags) to the compile (eg, -DLINUX in the Makefile).
For example, if your applications are in the files one.c and two.c, the linking command would be something like:
cc one.c two.c -lx25or
cc one.c two.c libx25.aIf you instead used:
cc one.c libx25.a two.cthen any library routines called in two.c would be left unresolved.
[ Functions | Contents | Tags | Errors ]
The library requires that a netid be used to identify a particular physical link. The administrator or installer configures a packetnets file to contain the mapping between a netid used by applications and either:
Before using X25getnetent, the functionX25setnetent 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 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.
[ Functions | Contents | Tags | Errors ]
The x25hostent structure is defined in X.25 Library Header File 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 /etc/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 an x25hostent structure associated with a given DNA (X.121 address) and Network ID, and X25gethostbyname to retrieve an x25hostent structure associated with a logical host name.
[ Functions | Contents | Tags | Errors ]
Although the software was designed to provide X.25 communications services, it also allows you to bypass the Packet Layer Protocol (Layer III of X.25) and make direct use of X.25 Level II (LAPB) by a program. LAPB, a transmission protocol used at the data link Level II, embeds information in a data frame that provides a single error free data channel. LAPB is a specific implementation of the HDLC protocol.
You select LAPB operation when configuring the system, usually at the time you install the software. See the Administrator's guide for details.
To simplify development of HDLC-only programs, we chose to use existing X.25 programming mechanisms to support HDLC/LAPB link operation. From a program's point of view, an HDLC/LAPB looks the same as one Permanent Virtual Circuit (PVC), and you use PVC-handling primitives to transfer information over the link.
The standard macros/errors/functions appropriate to LAPB are X25_ISHDLC(ct) , X25HDLCSYN, X25hdlcattach, X25hdlcdetach, X25open and X25close.
[ Functions | Contents | Tags | Errors ]
The library has two mechanisms to determine the availability of data packets on one or more circuits.
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.
Under Unix and Linux select() and poll() may be employed to investigate file descriptors for readability and writability.
The recommended method for multi-circuit applications under Windows 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.
[ Functions | Contents | Tags | Errors ]
These functions are used to access the x25hosts file using the x25hostent structure.
These function are used to access the packetnets file using the x25netent structure.
ct is of type CALLT *
[ Functions | Contents | Tags | Errors ]
/*************************************************************
* Module Name: libtest.c
*
* Description:
* Sends a string 100 times over an X.25 link
*************************************************************
#include <stdio.h>
#include <libx25tcp.h>
#define NUMPACKETS 100
int 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 NUMPACKETS times
* prepended by its 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);
}
[ Functions | Contents | Tags | Errors ]
On older versions of the library only the exported variable x25errno may be used to ascertain the current error code. The following is a list of error codes which X25geterror() or X25geterrorct() may return or which x25errno may take on. If the returned code is set to X25SYSERR check the return from X25getsyserror() or X25getsyserrorct() or errno (on Unix/Linux) for more details. X25error() or X25errorct() 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.
|
Error Code |
Description |
|
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 CALLT |
|
X25BADPID |
Bad Protocol ID specification |
|
X25BADDEFAULT |
Bad Default listener. Likely another default listener exists |
|
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 /etc/x25hosts or packetnets file |
|
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. Use X25accept() to complete the call setup. |
|
X25BADNUI |
Bad NUI Syntax |
|
X25FACLEN |
Facility String Too Long |
|
X25PVCSYN |
Syntax Error in PVC String |
|
X25BADNULL |
Bad Null-protocol Listener |
|
Syntax Error in HDLC/LAPB 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. /etc/x25hosts or packetnets. |
|
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 /etc/x25hosts |
| X25BADPOINTER | Bad Pointer was provided to a function |
| X25ISAPVC | API call is not valid for a PVC |
| X25PVCDISC | Phone line disconnected for dialup PVC |
| X25INVHANDLE | A handle was found to be invalid. |
| Errors which apply only to the SyncServer | |
|---|---|
| X25TCPBADHOST | Bad host name or IP address found in network ID in packetnets. |
| X25CANTCONNECT | Could not connect to the remote SyncServer. |
| X25TCPCLOSED | The TCP connection was closed unexpectedly by the remote SyncServer. |
| X25TIMEOUT | TCP communication with the remote SyncServer timed out. |
[ Functions | Contents | Tags | Errors ]
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.
|
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 |
|
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
|
|
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 |
|
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 |
|
T_TIMEOUT |
The number of seconds to block before returning
unsuccessfully. The present timeout delay is stored in the
global variable |
|
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 incoming 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 called Data Network Address buffer, used in conjunction with the T_DNALEN tag. Pass a value of type (char *). |
|
T_DNALEN |
Length of called 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 the caller wishes to pass when making a call. Pass a value of type (char *). |
|
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 incoming 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 incoming 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 structure, which contains connection parameters for SVCs. This tag is useful for setting or obtaining many parameters at once. Pass a value of type (cps *). The memory used for the CPS structure must remain valid throughout the duration of the call. That is, do not use a local/stack structure in functions that are completed before the SVC becomes inactive. |
|
T_PVCP |
Pointer to a fully qualified _pvcdesc structure, 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 X.25 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 file. Pass a value of type (char *) when specifying the network name. |
|
T_LISTENTYPE |
Type of listen 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 *). |
|
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 /etc/x25hosts file. Pass a value of type (int *) when specifying the host name. |
|
T_HOSTADDR |
Remote host address string from the /etc/x25hosts file. Pass a value of type (int *) when specifying the host name. |
|
T_NOWAIT |
No-wait flag. If FALSE (zero, the default), 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. |
| Tags which apply only to the SyncServer | |
|---|---|
|
T_SYNCTCP |
A boolean. Set to TRUE if Synchronous mode X.25 over TCP is to be employed. FALSE if not (the default) |
[ Functions | Contents | Tags | Errors ]
This header file contains constants and data structures needed for proper compilation. Please see libx25tcp.h for details. Note that some older products use libx25.h instead
Prototypes for the library functions can be found in libx25tcpprotos.h.[ Functions | Contents | Tags | Errors ]
The x25netent structure contains information on the attached links which are usable for synchronous communications. 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 X.25 Library Header file for the full definition of the x25netent structure.
[ Functions | Contents | Tags | Errors ]
Copyright © $Date: 2004/04/28 13:41:19 $
The Software Group Limited. All Rights Reserved.
® Netcom is a registered trademark of The
Software Group Limited.