PocketCNetLib | VisualNewt Software | Serg Koren

PocketCNetLib Sample Code

Mon, 09 Apr 2007 14:25:58 -0400

PocketCNetLib API Test Program 1.0.0

// PocketCNetLib test
// This is a simple PocketC program to test the PocketCNetLib.
// PocketCNetLib is a native library that allows PocketC to connect to the internet.
//
// PocketCNetLib
// VisualNewt Software
// http://www.VisualNewt.com/
// Serg@VisualNewt.com
//
// PocketCNetLib is (c) 2003 Serg Koren & VisualNewt Software.
//	All rights reserved.
// PocketCNetLib is $10.
//
// use the 'library' statement to get access to the library
library "PocketCNetLib"
// app stuff
@cid "VNNL";
@name "PocketCNetLib test";
@dbname "PCNL test";
@ver "1.0.0";
// globals
int refnum;
int socketrefnum;
int err;
// For returned strings...some of the library calls return a pointer to a string.
pointer p;
@doc "Translate an error code into a string.";
ConvertError(int err)
{
		// pass in the error code returned by the library
		p = nlErrorString(err);
		puts(*p + " " + (err - 5000) +  "\n");
		alert(*p + " " + (err - 5000));
		exit();
}
@doc "Releases the NetLib";
CleanupLibrary()
{
		// close the library
		err = nlNetLibClose(refnum,0);
		if (err > 5000)
		{
			ConvertError(err);
		}
		puts("Library closed\n");
}
@doc "Gets a reference to the NetLib and opens it.";
SetupLibrary()
{
		// get the refnum to library
		refnum =  nlGetNetLibNumber();
		if (err > 50000)
		{
			ConvertError(refnum);
		}
		puts("NetLib Reference number: " + refnum + "\n");
		// set timeout to 5 seconds
		err = nlSetAppNetTimeout(5);
		if (err > 5000)
		{
			CleanupLibrary();
			ConvertError(err);
		}
		puts("Timeout set\n" );
		// open the library
		err = nlNetLibOpen(refnum);
		if (err >  5000)
		{
         	CleanupLibrary();
			ConvertError(err);
		}
		puts("Library opened\n");
}
@doc "Opens a socket.";
ObtainSocket()
{
		// open a socket
		socketrefnum  = nlNetLibSocketOpen(refnum,2,1,5000);
		if (socketrefnum > 5000)
		{
			CleanupLibrary();
			ConvertError(err);
		}
		puts("Socket number : " + socketrefnum + "\n");
}
@doc "Closes the socket.";
ReleaseSocket()
{
		// close the socket
		err = nlNetLibSocketClose(refnum,socketrefnum,5000);
		if (err > 5000)
		{
			CleanupLibrary();
			ConvertError(err);
		}
		puts("Socket closed.\n");
}
@doc "Connects to either the dottedIP or host name at the specified port.";
ConnectSocketToAddress(string dottedIP, string port)
{
		string buf = dottedIP;
		buf = buf + " translated to ";
		// Get a socket reference number by opening a socket
		ObtainSocket();
		// look up our test DNS name's IP address...
		puts("Checking " + dottedIP + "\n");
		// see if the first char is a number...if so it's a dotted IP, otherwise its a DNS name;
		// if its a DNS name we need to get the dotted IP equivalent.
		dottedIP = strlwr(dottedIP);
		if ((dottedIP@[0] >= "a") && (dottedIP@[0] <= "z"))
		{
			p = nlNetLibGetHostByName(refnum,dottedIP,5000);
			puts(dottedIP + " - " + *p + "\n");
			// length of 4 indicates an error code
			if (strlen(*p) == 4)
			{
				// convert the error in string form to an interger
				err = *p;
				ReleaseSocket();
				CleanupLibrary();
				ConvertError(err);
			}
		}
		// connect the socket
		// note you can also just pass in the DNS name instead of the IP address.
		// ( www.visualnewt.com instead of xxx.xxx.xxx.xxx since nlNetLibSocketConnect
		//   does its own NetLibGetHostByName if needed.)
		err = nlNetLibSocketConnect(refnum,socketrefnum,*p,port,5000);
		if (err == 5003)
		{
			// The demo library is locked into www.visualnewt.com
			alert("This is a demo copy of PocketCNetLib: " + (err - 5000));
			puts("This is a demo copy!\n");
			ReleaseSocket();
			CleanupLibrary();
			exit();
		}
		else if (err > 5000)
		{
			ReleaseSocket();
			CleanupLibrary();
			ConvertError(err);
		}
		puts("Socket connected: " + *p + ":" + port + "\n");
}
@doc "Sends the specified data to our socket.";
SendData(string what)
{
		err = nlNetLibSend(refnum,socketrefnum,what,0,"","",5000);
		if (err > 5000)
		{
			ReleaseSocket();
			CleanupLibrary();
			ConvertError(err);
		}
		puts("Socket sent data! Bytes: " + err + "\n");
}
@doc "Receives data from our socket.";
GetData()
{
 		puts("Receiving response.\n");
		p =  nlNetLibReceive(refnum,socketrefnum,0,5000);
		// length of 4 indicates an error code
		if (strlen(*p) == 4)
		{
			// convert error in string form to integer
			err = *p;
			ConvertError(err);
		}
		puts("RECEIVED:\n");
		puts (*p + "\n");
		puts("END RECEIVED\n");
}
@doc "Make sure the NetLib is installed.";
CheckAvailability()
{
		err = nlCheckInstalled();
		if (err > 5000)
		{
			alert("NetLib not installed or available: " + (err - 5000));
			puts("NetLib not installed or available: " +  (err - 5000));
			exit();
		}
		puts("NetLib is available.\n");
}
// The main routine
// 	This is structured into high-level functionality.
@doc "Main routine.";
main()
{
		// Clear the output
		clear();
		// Display a title with the PocketCNetLib version.
		// It should not return a 0
		p = nlVersion();
		if (*p == 0)
		{
			alert("Cannot connect to library.");
			exit();
		}
		title("PocketCNetLib Test - " + *p);
		puts("Version: " + *p + "\n");
		// Make sure the NetLib is installed and available.
		CheckAvailability();
		// Set up the Net library
		SetupLibrary();
		// Connect a socket to an address, port number
		// The demo library only connects to www.visualnewt.com
		// Register to get an unlocked version.
		ConnectSocketToAddress("www.VisualNewt.com","80");
		// Now send data to our socket -- in this case we call a web page
		SendData("GET /Products/Palm/PocketCNetLIb/test.html HTTP/1.0\r\n\r\n");
		// Receive data from our socket
		GetData();
		// Close the socket we have open
		ReleaseSocket();
		// Tear down the Net library
		CleanupLibrary();
		puts("Done!");
		alert("Done!");
}

Support:

PocketCNetLib support is a development tool. As such, only the tool is supported, not any code you attempt to develop using the tool. It is up to you to determine whether the problem is in your code or the library's. Support will be provided to registered users only, and priority will be given to registered users for enhancement requests.

Bugs and enhancement requests should be sent to: Serg@VisualNewt.com

PocketCNetLib Documentation

Mon, 09 Apr 2007 14:24:08 -0400

PocketCNetLib API 1.0.0

© 2003 Serg Koren & VisualNewt Sofware.
All rights reserved.

The following NetLib API calls are supported internally by the library:

NetLibReceive

NetLibGetHostByName

NetLibSend

NetLibSocketConnect

NetLibSocketClose

NetLibSocketOpen

NetLibClose

NetLibOpen

SetAppNetTimeout

GetNetLibNumber

(others will be added as requested by registered users.)

The PocketCNetLib API calls (exposed to PocketC) include:

nlVersion

nlCheckInstalled

nlGetNetLibNumber

nlErrorString

nlNetLibOpen

nlNetLibGetHostByName

nlNetLibSocketConnect

nlNetLibSocketOpen

nlNetLibSend

nlNetLibReceive

nlNetLibSocketClose

nlNetLibClose

nlSetAppNetTimeout

See the example test program for a complete example of the API's use.

pointer nlVersion();

parameters:

<none>

Returns the version number of the PocketCNetLib. The return is a pointer to a string.
pointer p;
p = nlVersion();
alert(*p);
    

int nlCheckInstalled();

parameters:

<none>

Returns 5000 if NetLib is installed on the device, otherwise returns an error code which can be passed to nlErrorString.

int nlGetNetLibNumber();

parameters:

<none>

Returns the NetLib reference number, otherwise returns an error code which can be passed to nlErrorString.

Note: the reference number will be less than 5000, while an erro code will be greather than 5000.

pointer nlErrorString(int errorCode);

parameters:

integer error code obtained from PocketCNetLib

Accepts an error code as returned by PocketCNetLib, and returns a pointer to the corresponding error string. NOTE: Do not pass non PocketCNetLib errors into this routine. PocketCNetLib error codes start at 5000. To get the corresponding PalmOS NetLib errror code merely subtract 5000 from the PocketCNetLib error code. That is:

PalmOS NetLib error code = PocketCNetLib error code - 5000;
pointer p;
p = nlErrorString(5122);
alert(*p);
int nlNetLibOpen(int refNum);

parameters:

integer NetLib reference number

Opens the NetLib given its reference number (obtained via nlGetNetLibNumber). Returns 5000 if successful, otherwise returns an error code that can be passed to nlErrorString.

pointer nlNetLibGetHostByName(int refNum,string hostName,int timeout);

parameters:

integer NetLib reference number

string host name to be translated

integer timeout in seconds

Translates a host name to a TCP/IP dotted-IP address of the form xxx.xxx.xxx.xxx. Returns a pointer to a string that eitherrepresents the dotted IP address or a 5000-based error code that can be passed to nlErrorString after conversion to an integer.
string host;
pointer p;
host = "www.palmsource.com";
p = nlNetLibGetHostByName(refnum,host,5);
puts(host + " - " + *p + "\n");
// length of 4 indicates an error code
if (strlen(*p) == 4)
{
    //handle errors here
}
int nlNetLibSocketConnect(int refNum,int socketNum,string host,string port,int timeout);

parameters:

integer NetLib reference number

integer socket reference number obtained from nlNetLibSocketOpen

string host name OR dotted IP address

string timeout in seconds

Attempts to connect to the specified host-port combination given the NetLib and socket reference numbers. This call will accept either a dotted IP address in the form of "255.255.255.255" or a host name "www.mysite.com", and will do an internal name to IP address lookup if necessary. Returns 5000 if the connection succeeds, otherwise it returns an error code that can be passed to nlErrorString.

NOTE: The demo version of PocketCNetLib will return an error code 5003 if the host or IP address maps to something other than www.visualnewt.com. That is, the demo will only connect to www.visualnewt.com.

int nlNetLibSocketOpen(int refNum,int domain, int type, int timeout);

parameters:

integer NetLib reference number

integer domain 0, or 2 (see PalmOS NetSocketAddrEnum documentation). You will usually use 2.

integer type 1,2,3,4 (see PalmOS NetSocketTypeEnum documentation). You will usually use 1.

integer timeout in seconds

Obtains a socket and attempts to open it. If successful, nlNetLibSocketOpen returns a socket reference number,otherwise a 5000-based error code that can be passed to nlErrorString.

nlNetLibSend(int refNum, int socketNum, string buffer, string dottedIP, string port, int timeout);

parameters:

integer NetLib reference number

integer socket reference number

string buffer to transmit (NOTE: This buffer is limited to 2048 bytes within PocketCNetLib.)

string dotted IP address of the host to send to or "" if you wish to send to the currently open socket. (NOTE: This call does not resolve host names.)

string port to send to or "" if you wish to send to the currently open socket.

integer timeout in seconds

Attempts to send a string buffer of data to the previously opened socket, or to the specified dotted IP address and port combination. Set the dotted IP and port numbers to "" to specify the previously opened socket. Returns the total number of bytes sent or a 5000 based error code that can be passed to nlErrorString.

pointer nlNetLibReceive(int netRef, int socketNum, int flags, int timeout);

parameters:

integer NetLib reference number

integer socket reference number

integer flags 0. (See PalmOS I/O Flags Documentation).

integer timeout in seconds

Reads data from the previously opened socket and returns a pointer to the data. Returns a pointer to a 5000 based string error code. This must be converted to an integer to be passed to nlErrorString.
int err;
pointer p; 
p = nlNetLibReceive(refnum,socketrefnum,0,5);
// length of 4 indicates an error code
if (strlen(*p) == 4)
{
// convert error in string form to integer
   err = *p;
   p = nlErrorString(err);
   alert(*p);
}
puts("RECEIVED : " + *p + "\n");
int nlNetLibSocketClose(int refNum, int socketNum, int timeout);

parameters:

integer NetLib reference number

integer socket reference number

integer timeout in seconds

Attempts to close the socket number specified. Returns 5000 if successful, or an error code that can be passed to nlErrorString.

int nlNetLibClose(int refNum, int closeMode);

parameters:

integer NetLib reference number

integer 0 = use timed close, 1 = close immediately (see PalmOS NetLib documentation).

Closes the NetLib. Returns 5000 if successful, or a 5000 based error code that can be passed to nlErrorString.

int nlSetAppNetTimeout(int timeout);

parameters:

integer timeout in seconds

Sets the AppNetTimeout variable that determines the application's timeout on network activity. See PalmOS NetLib documentation for more information. This call always returns 5000 (success).

Support:

PocketCNetLib support is a development tool. As such, only the tool is supported, not any code you attempt to develop using the tool. It is up to you to determine whether the problem is in your code or the library's. Support will be provided to registered users only, and priority will be given to registered users for enhancement requests.

Bugs and enhancement requests should be sent to: Serg@VisualNewt.com