1 - NetAPI5 Design Overview
1.1 - NetAPI5 Files
1.2 - NetAPI5 Calling Conventions
2 - NetAPI5 Data Structures
2.1 - NetAPI5_Filter
2.2 - NetAPI5_Country
2.3 - NetAPI5_Phone
2.4 - NetAPI5_Modem
2.5 - NetAPI5_File
2.6 - NetAPI5_Connect
3 - NetAPI5 Functions - C/C++ Interface
3.0 - Enable/Disable and Version Interface
3.0.1 - NetAPI5_EnableApi
3.0.2 - NetAPI5_SetNetApiVersion
3.0.3 - NetAPI5_GetNetApiVersion
3.0.4 - NetAPI5_GetNetClientVersion
3.0.5 - NetAPI5_DisableApi
3.1 - Data Interface
3.1.1 - NetAPI5_SetLocationNpaNxx
3.1.2 - NetAPI5_GetPhoneCountryCount
3.1.3 - NetAPI5_GetPhoneCountryData
3.1.3 - NetAPI5_GetPhoneNumberCount
3.1.4 - NetAPI5_GetPhoneNumberData
3.1.5 - NetAPI5_GetModemCount
3.1.6 - NetAPI5_GetModemData
3.1.7 - NetAPI5_GetFileCount
3.1.8 - NetAPI5_GetFileData
3.2 - Connection Action Interface
3.2.1 - NetAPI5_ConnectStart
3.2.2 - NetAPI5_ConnectStatus
3.2.3 - NetAPI5_ConnectEnd
3.3 - Update Action Interface
3.3.1 - NetAPI5_UpdateStart
3.3.2 - NetAPI5_UpdateStartIfNewer
3.3.3 - NetAPI5_UpdateStatus
3.3.4 - NetAPI5_UpdateEnd
4 - NetAPI5 Functions - Visual Basic Interface
5 - NetAPI5 Status Codes and States
5.1 - Status Codes
5.1.1 - State Code Values
5.1.2 - Error Code Values
5.2 - State Transition Diagram
6 - NetAPI5 Usage
6.1 - An Example Application
6.2 - Building The Example Application
The NetAPI5 (NetClient Application Program Interface) component (Version 5) is a standard part of the Net Client product. When driven by NetAPI5 functions, the Net Client product has no user interface. A customer-written application can utilize NetAPI5 to:
| navigate the phone list | |
| examine version information for the phone list files | |
| initiate, monitor and terminate connections | |
| request updates to the phone list files |
It is the responsibility of the customer-written application to supply any required user interface dialogs, status messages, etc.
NetAPI5 consists of the following files:
NetAPI5.h . . . . C/C++ program header NetAPI5.lib . . . static link library (stub) NetAPI5.dll . . . dynamic link library (implementation) NetAPI5.bas . . . Visual Basic interface definition NetAPI5 functions are defined in NetAPI5.h, exported via NetAPI5.lib, and implemented in NetAPI5.dll. These files will all ship as a standard part of the Net Client product.
All NetAPI5 functions are available in both C/C++ and Visual Basic language calling conventions.
All structures must be packed on byte boundaries (the expected total size in bytes of each structure type is shown below).
The NetAPI5.h header file contains the following #pragma to instruct most
compilers to honor this requirement:
#pragma pack(1)
All fields of type char[ ] (character array) are ASCIIZ strings (null terminated).
ASCIIZ strings which represent numbers are radix-10 integers.
Empty (zero-length) ASCIIZ strings may occur for some string fields.
Use empty strings for any optional fields which you wish to leave unspecified.
All fields of type char (single character) are flags with values of character 0 (zero) or binary zero for FALSE and character 1 (one) or binary 1 for TRUE.
The Filter structure encodes the Feature and Modem types which are used to filter the phone list. Specify one of the Modem Type strings, and one or more of the Feature strings. If specifying more than one required feature, seperate features with '+' (plus sign) characters.
typedef struct { int Size ; // structure size char Feature [80]; // desired feature mix char ModemType[ 8]; // desired mode types } a_NetAPI5_Filter; #define s_NetAPI5_Filter 92 // structure sizeModem Types
"AX" - async or combined async+isdn "AXD" - async, isdn, or combined async+isdn "XD" - Combined async+isdn, or isdn Features
"AGN" - AT&T Global Network "IP1" - Secure IP Dial "IP2" - Internet Dial "IP3" - Dual Access "HIC" - Corporate internet "HIP" - Consumer internet "HVA" - Intranet
The NetAPI5_Country structure encodes the standard two-character ISO 3166 country code (such as 'US' for the United States) and the country name (in English) for a specific country.
typedef struct { int Size ; // structure size char IsoCode [ 4]; // ISO 3166 country code char TapiCode [ 4]; // TAPI country code char ExitPrefix [ 6]; // outbound direct dial prefix char EntryPrefix [ 6]; // inbound direct dial prefix char DeletePrefix[ 6]; // international Delete prefix char CountryName [62]; // country name } a_NetAPI5_Country; #define s_NetAPI5_Country 92 // structure size
The NetAPI5_Number structure encodes information about a specific phone number. A special Tag value is included which uniquely identifies the the phone number. The Tag value is required by NetAPI5 functions which initiate a connection to a phone number.
typedef struct { int Size ; // structure size char RegionName [60]; // region name (may be zero-length) char PhoneNumber[24]; // phone number (formatted, long distance form) char CityName [60]; // city name char Comment [60]; // text comment (may be zero-length) char NetworkId [ 4]; // network identifier (AGN/XN1/XN2/XN7) char Distance [10]; // fixed format, like ' 398 mi' or '12345 km' char Zone [16]; // like 'Local [2]' or 'Long Distance' char AsyncFlag ; // async modem flag (1/0) char IsdnFlag ; // isdn modem flag (1/0) char TollFlag ; // toll flag (1/0) char HelpFlag ; // helpdesk flag (1/0) char Padding[2] ; // reserved (set to zero) } a_NetAPI5_Number; #define s_NetAPI5_Number 244 // structure size
The NetAPI5_Modem structure encodes information about available modems.
typedef struct { int Size ; // structure size char ModemName[80]; // Modem name char ModemType[17]; // Modem type char Padding [ 3]; // reserved (set to zero) } a_NetAPI5_Modem; #define s_NetAPI5_Modem 104 // structure size
The NetAPI5_File structure encodes information about specific files which make up the phone list (there may be more than one). For each file, the internal date/time stamp is returned, along with the number of days left before an update is suggested. The file size is returned to help make a decision about an update request.
typedef struct { int Size ; // structure size int FileSize ; // file size in bytes int DaysLeft ; // days remaining before update suggested char FileTime[20]; // like '1999/08/26 12:23:03' char FileName[80]; // file name (8.3 format) } a_NetAPI5_File; #define s_NetAPI5_File 112 // structure size
The NetAPI5_Connect structure encodes the information necessary to initiate a connection using the NetAPI5_ConnectStart() call. If you need to specify a Service, use one of the Service Type strings shown below.
typedef struct { int Size ; // structure size char PhoneNumber[80]; // from NetAPI5_Number structure (omit to use existing connection) char NetworkId [ 4]; // from NetAPI5_Number structure char ModemName [80]; // from NetAPI5_Modem structure (omit to use existing connection) char Service [16]; // AGNS service (optional) char Account [10]; // AGNS account (optional) char UserId [80]; // AGNS userid (or email userid) char Password [80]; // AGNS password (or email password) char NewPassword[80]; // new AGNS password (or email password) char Dns1 [16]; // primary DNS server (optional) char Dns2 [16]; // secondary DNS server (optional) char Wins1 [16]; // primary WINS server (optional) char Wins2 [16]; // secondary WINS server (optional) char IpxSpxFlag ; // IPX/SPX flag ('1'/'0') char NetBeuiFlag ; // NetBEUI flag ('1'/'0') char LanLogonFlag ; // LAN logon flag ('1'/'0') char Padding [ 3]; // reserved (set to zero) } a_NetAPI5_Connect; #define s_NetAPI5_Connect 504 // structure sizeService Types
"internet" - Internet "secureip" - Secure "dualaccess" - DualAccess "fixedip" - FixedIp "3d" - FixedIp3d "vi" - VpnIpsec "vida" - VpnIpsecDa "vp" - VpnPptp "vpm" - VpnPptpMp "default" - Default
The functions provided via NetAPI5 can set phone list filters, query phone numbers, query modems, query file information, and trigger or cancel key Net Client behaviors. This section describes the calling interfaces for these functions when used by C/C++ programs. These programs should include the NetAPI5.h header file when compiled, and the NetAPI5.lib file when linked.
The version interface allows the programmer to initialize the API, check the API version, and check the Net Client Application Version
NetAPI5_EnableApi
Invoke this macro to initialize the API. It calls the NetAPI5_SetNetApiVersion() function with the NetAPI5_Version macro as an argument.
NetAPI5_SetNetApiVersion
This function initializes the API. It must be called prior to any other use of the API. You must pass the value of the API version string which corresponds to the version of the API your application was designed to work with. This value can be found in the NetAPI5.h header file in the macro named NetAPI5_Version.
t_NetAPI5_Status NetAPI5_SetNetApiVersion( char * ApiVersion);Parameters
char * ApiVersion [in] the API version required by your application
Return Values
This function returns a NetAPI5 Status Code.NetAPI5_GetNetApiVersion
This function will return the version of the NetAPI5.
char * NetAPI5_GetNetApiVersion();Parameters
This function does not take any parameters.Return Values
This function returns a char * value indicating the NetAPI5 version.NetAPI5_GetNetClientVersion
This function will return the version of the Net Client Application.
char * NetAPI5_GetNetClientVersion();Parameters
This function does not take any parameters.Return Values
This function returns a char * value indicating the Net Client Application's version.NetAPI5_DisableApi
This function will terminate the NetAPI5 session. Well-behaved applications will call this function when they no longer need NetAPI5 services.
void NetAPI5_DisableApi();Parameters
This function does not take any parameters.Return Values
This function does not return any value.
The Data interface allows the programmer to get data on phone numbers, modems, or updateable files.
NetAPI5_SetLocationNpaNxx
Call this function to set the user location by specifying the telephone area code (Npa) and exchange (Nxx).
int NetAPI5_SetLocationNpaNxx( int Npa, int Nxx);Parameters
int Npa [in] the area code
int Nxx [in] the exchange
Return Values
This function returns an int value indicating the number of Countries that support the required modem types and features.NetAPI5_GetPhoneCountryCount
This function will determine the number of Countries that support the features and modem types you wish to connect to.
int NetAPI5_GetPhoneCountryCount( a_NetAPI5_Filter * Filter);Parameters
a_NetAPI5_Filter * Filter [in] a pointer to a NetAPI5_Filter Structure
Return Values
This function returns an int value indicating the number of Countries that support the required modem types and features.NetAPI5_GetPhoneCountryData
This function will provide Phone Country data.
const a_NetAPI5_Country * NetAPI5_GetPhoneCountryData( int CountryIndex);Parameters
int Countryindex [in] An Integer Country index value.Return Values
This function returns a pointer to a a_NetAPI5_Country value containing the data associated with the Country referenced by the CountryIndex paramater. In the event of an error, a NULL (undefined pointer) value is returned.NetAPI5_GetPhoneNumberCount
This function will determine the number of Phone Numbers in the Phone List for the Country specified by the Country index.
int NetAPI5_GetPhoneNumberCount( int CountryIndex);Parameters
int CountryIndex [in] An Integer Country index value.Return Values
This function returns an int value indicating the number of phone numbers which match the requested Country index.NetAPI5_GetPhoneNumberData
This function will provide Phone Number data.
const a_NetAPI5_Number * NetAPI5_GetPhoneNumberData( int NumberIndex);Parameters
int NumberIndex [in] An Integer Number index value. This is obtained by calling NetAPI5_GetPhoneNumberCountReturn Values
This function returns an a_NetAPI5_Number value containging the data associated with the number passed in Numberindex.NetAPI5_GetModemCount
This function will determine the number of modems installed on the clients PC.
int NetAPI5_GetModemCount( void);Parameters
This function does not take any parameters.Return Values
This function returns an int value indicating the number of modems installed on the clients PC.NetAPI5_GetModemData
This function will retrieve data associated with the modems.
const a_NetAPI5_Modem * NetAPI5_GetModemData( int ModemIndex);Parameters
ModemIndex [in] An index of the modem you would like to retrieve data on. This must be a value obtained by calling GetModemCount.Return Values
This function returns a pointer to a_NetAPI5_Modem value containing the modem data requested. In the event of an error, a NULL (undefined pointer) value is returned.NetAPI5_GetFileCount
This function will get the count of Phone List Files.
int NetAPI5_GetFileCount( void);Parameters
This function does not take any parameters.Return Values
This function returns an int value indicating the number of Phone list files.NetAPI5_GetFileData
This function will retrieve data associated with the Phone List files.
const a_NetAPI5_File * NetAPI5_GetFileData( int FileIndex);Parameters
FileIndex [in] An index of the File you would like to retrieve data on. This must be a value obtained by calling GetFileCount.Return Values
This function returns a pointer to a a_NetAPI5_File value containing the file data requested. In the event of an error, a NULL (undefined pointer) value is returned.
The Connection Action Interface allows the programmer to control a connection.
NetAPI5_ConnectStart
This function connects the Net-Client to the network.
t_NetAPI5_Status NetAPI5_ConnectStart( a_NetAPI5_Connect * Connect);Parameters
a_NetAPI5_Connect [in] A pointer to a Connect structureReturn Values
This function returns a NetAPI5 Status Code.NetAPI5_ConnectStatus
This function indicates the state of the connection operation. It is also used to register a callback function receives notifications of state changes.
t_NetAPI5_Status NetAPI5_ConnectStatus( void (* Callback)(t_NetAPI5_Status Status));Parameters
void (* Callback)( int Status) [in] This function takes a pointer to a callback function, which will receive notifications of state changes, as a parameter.Return Values
This function returns a NetAPI5 Status Code indicating the current NetAPI5 Status.NetAPI5_ConnectEnd
This function disconnects the Net-Client connection from the network.
t_NetAPI5_Status NetAPI5_ConnectEnd( void);Parameters
This function does not take any parametersReturn Values
This function returns a NetAPI5 Status Code indicating the success or failure of the disconnect operation.
The Update Action Interface allows the programmer to initiate or cancel a update operation.
NetAPI5_UpdateStart
This function attempts to download updated files.
t_NetAPI5_Status NetAPI5_UpdateStart( a_NetAPI5_File * File);Parameters
a_NetAPI5_File [in] A pointer to a NetAPI5_File structure.Return Values
This function returns a NetAPI5 Status Code.Remarks A call to this function will change the Net-Client state to NetAPI5_Update_Updating.
NetAPI5_UpdateStartIfNewer
This function attempts to download updated files if newer files are available than the ones currently installed.
t_NetAPI5_Status NetAPI5_UpdateStartIfNewer( a_NetAPI5_File * File, int DownloadRegardless);Parameters
a_NetAPI5_File * File [in] A pointer to a NetAPI5_File structure. int DownloadRegardless [in] A flag value (nonzero is true).Return Values
This function returns a NetAPI5 Status Code.Remarks A call to this function will change the Net-Client state to NetAPI5_Update_Updating.
NetAPI5_UpdateStatus
This function indicates the state of the Update operation. It is also used to register a callback function receives notifications of state changes.
t_NetAPI5_Status NetAPI5_UpdateStatus( void (* Callback)(t_NetAPI5_Status Status));Parameters
void (* Callback)( int Status) [in] This function takes a pointer to a callback function, which will receive notifications of state changes, as a parameter.Return Values
The return value is a NetAPI5 Status Code.NetAPI5_UpdateEnd
This function Ends an Update operation in progress.
int NetAPI5_UpdateEnd( void);
Parameters
This function does not take any parametersReturn Values
This function returns a NetAPI5 Status Code indicating the success or failure of the Update End operation.
The Visual Basic interface is closely related to the C/C++ interface documented above. The differences are as follows:
| There is no NetAPI5_EnableApi() function. Use the NetAPI_SetNetApiVersion() function instead. | ||
| The calling conventions of all functions which return pointers to structures (like NetAPI5_Country *) or strings (like char *) are modified to return a long value instead, and to take an extra parameter which is a pointer to a user-supplied buffer of adequate size to accept a copy of the expected structure or string, and into which the return structure or string is copied on success. For functions in this category, a nonzero long return value indicates a good return, while a zero return value indicates an error (in which case the contents of the user-supplied buffer are undefined and should not be used). |
The status interface returns integer codes representing the state of the Net Client system. The customer-written application is responsible for displaying appropriate messages to a user as appropriate. Status codes are formed from two components: a State Code and an Error Code. The value of a status code is equal to:
(State_Code * 1000) + Error_CodeThe following values are currently defined:
State Code Values
NetAPI5_Init_Ready = 1100, NetAPI5_Init_Error = 1999, NetAPI5_Connect_Ready = 2100, NetAPI5_Connect_Dialing = 2200, NetAPI5_Connect_AuthenticatingDial = 2300, NetAPI5_Connect_Tunneling = 2400, NetAPI5_Connect_AuthenticatingTunnel = 2500, NetAPI5_Connect_Connected = 2600, NetAPI5_Connect_Disconnecting = 2700, NetAPI5_Connect_Disconnected = 2800, NetAPI5_Connect_Error = 2999, NetAPI5_Update_Ready = 4100, NetAPI5_Update_Updating = 4200, NetAPI5_Update_Updated = 4300, NetAPI5_Update_Canceled = 4400, NetAPI5_Update_Error = 4999,Error Code Values
NetAPI5_Ok = 0, NetAPI5_Error_ApiNotInitialized = 101, NetAPI5_Error_DunNotInstalled = 102, NetAPI5_Error_TcpIpNotInstalled = 103, NetAPI5_Error_ApiAlreadyRunning = 104, NetAPI5_Error_FailedDBInit = 105, NetAPI5_Error_ProfileCreate = 106, NetAPI5_Error_ConnectCreate = 107, NetAPI5_Error_NotConnected = 108, NetAPI5_Error_InvalidParameter = 109, NetAPI5_Error_InvalidPassword = 201, NetAPI5_Error_InvalidNewPassword = 202, NetAPI5_Error_ExpiredPassword = 203, NetAPI5_Error_NextCardCode = 204, NetAPI5_Error_NewPin = 205, NetAPI5_Error_InvalidUserId = 206, NetAPI5_Error_CannotAuthenticate = 207, NetAPI5_Error_CommPortError = 208, NetAPI5_Error_CommPortWarning = 209, NetAPI5_Error_FatalLoginError = 210, NetAPI5_Error_IncorrectService = 211, NetAPI5_Error_NoISDNAccess = 212, NetAPI5_Error_NoAutoBackup = 213, NetAPI5_Error_NoISDNSurchage = 214, NetAPI5_Error_NoWireless = 215, NetAPI5_Error_NoAnalogAccess = 216, NetAPI5_Error_NoISDNAutoBackup = 217, NetAPI5_Error_NoAnalogSurcharge = 218, NetAPI5_Error_NoWirelessSurcharge = 219, NetAPI5_Error_NoAccessAccount = 220, NetAPI5_Error_NoAccessUserid = 221, NetAPI5_Error_PasswordRevoked = 222, NetAPI5_Error_ExcessiveLogins = 223, NetAPI5_Error_NotAuthLandial = 224, NetAPI5_Error_NoPrimaryTunnels = 225, NetAPI5_Error_AccountNotAllowed = 226, NetAPI5_Error_NoDefaultNetwork = 227, NetAPI5_Error_UserServiceMismatch = 228, NetAPI5_Error_CannotContactSIG = 229, NetAPI5_Error_NoSIGforUser = 230, NetAPI5_Error_ServiceUnavailable = 231, NetAPI5_Error_NoAccessAccountUser = 232, NetAPI5_Error_UseridNotAuth = 233, NetAPI5_Error_InternalError = 999In addition to the above codes, RAS error codes may be returned to indicate a connection failure. RAS error codes are always in the range 600 to 799.
Here is the shell of a simple C/C++ application which utilizes NetAPI5. For a more complete
example, see NetApiExample.cpp.
#include <stdio.h>
#include "NetAPI5.h"
void main( void) {
if (NetAPI5_State( NetAPI5_EnableApi()) != NetAPI5_Init_Ready) {
printf( "Couldn't initialize NetAPI5!\n");
return;
}
printf( "NetAPI5 version = '%s'\n", NetAPI5_GetNetApiVersion ());
printf( "Net Client version = '%s'\n", NetAPI5_GetNetClientVersion());
NetAPI5_DisableApi();
}
Assuming this example program is in a file named Example.cpp, it can be compiled and linked (with Microsoft
Visual C/C++) with the following command:
cl Example.cpp NetAPI5.lib
