NicToolServer API Documentation for SOAP and XML-RPC (v2.00b)
Prev Next

API Notes

NicToolServer provides a rich set of function calls which may be called with the SOAP or XML-RPC protocols, using HTTP (or preferably, HTTPS) as a transport layer. First a session must be created with the login function. When you are done with your session, it may be terminated with the logout function. Your session will timeout after a certain amount of time has passed with no activity, and you will be required to login again.

Data types. The data types used by NicToolServer are fairly simple:

  • struct. A hash table of name/value pairs.

  • string. A string of characters

  • int. A number

  • array. A list of other values

  • flag. This is a boolean value represented by a string. It should be either '1' meaning TRUE or '0' meaning FALSE.

The struct, or perl hash table, is returned by all functions, and is the type of the only parameter of every function. Most values contained within the hashtable are either a string, an int, or other hashtables. Also used are array elements. Refer to the SOAP 1.2 spec for more information about these data types in SOAP, and the XML-RPC spec for information about these data types in XML-RPC.

Function calling.

Note: Function names are case insensitive.

All functions take as a parameter one struct, and all functions return one struct. Typically there will be a number of required named entries in a struct parameter.

Note: Named parameters inside structs are case sensitive.

These required entries are listed within each function's definition below.

Special parameters. There is one named parameter that is required by all function calls. It should be included along with the other named hash entries in all function calls, unless noted:

nt_user_session

The session ID string. This string is required for all functions other than login

Also the optional nt_protocol_version has special meaning. If you specify a version number with it (like "1.0") the NicTool Server will return an error unless it supports the given version. If you do not specify it, no version check is performed. This allows clients who wish to guarantee that their protocol version will work to do so, but it also allows clients to attempt to interact with a server without checking the version number of the protocol.

Note: The only protocol version supported by NicTool Server 2.00b is "1.0"

nt_protocol_version

a string naming the protocol version in use by the client agent



Errors. If a function call encounters an error, three entries in the returned hash will contain the error code, a short description of the error, and the specific error message. If no error occurs, these three entries may still be present. The returned named entry error_code will have a value other than "200" if the result is an error.

error_code

string. Code number of the error. "200" indicates that no error has occurred.

error_desc

string. Short description of the error. "OK" is the normal response if there is no error.

error_msg

string. The full error message. "OK" is the normal response if there is no error.



Prev Home Next
Changes since version 1.06x   NicTool Objects