NOTE: For the PocketPC platform, see the PocketPC Winsock extension which is equivalent to this PalmOS extension.

The Internet Extension allows Satellite Forms applications to connect to TCP/IP based networks (such as the Internet). It is a minimal implementation of the Berkeley sockets standard. With the Internet Extension your application can connect to hosts and send/receive data. 

Scripts API

The following methods are accessible from the scripting language.  Please note that this extension is recommended for those developers who understand the Berkeley socket standard.  These methods are all global unless noted.

Global Method

Example of usage:  [Name of method]

Example of usage:  OpenNetLib()

Private Method

Example of usage:  [Name of extension].[Name of method]

Example of usage:  Extensions(“Internet Extension”).About()

About()

A private method that shows the extension's about box.

Close(integer)

Closes a socket.  Returns: zero for success, non-zero for an error condition. 

Example of usage: err = Close( socketRef ), where socketRef is a valid socket reference.

CloseNetLib(integer)

Closes the net library.  Returns: zero for success, non-zero for an error condition. 

Example of usage: err = CloseNetLib( immediate ), where 'immediate' is 0 or 1 indicating whether the connection should be dropped immediately (it's preferable to leave it open so the user can switch to another network app).

Connect(integer, string, integer)

Connects a socket to a specified address and port.  Returns: zero for success, non-zero for an error condition. 

Example of usage: err = Connect( socketRef, addr, port ), where 'socketRef' is a valid socket reference, 'addr' is a valid dotted decimal IP address and 'port' is the port number to connect to.

ConvertDottedToInetAddr(string)

Converts a dotted decimal address (aaa.bbb.ccc.ddd) into a 32-bit network address.

ConvertInetAddrToDotted(string)

Converts a 32-bit network address into a dotted decimal address (aaa.bbb.ccc.ddd).

GetDomainName()

Retrieves the default domain added to names before DNS lookups occur.

GetHostByAddr(string)

Performs a reverse DNS lookup on the passed IP address, returning the name of the host machine.  Returns: a string formatted as <errorCode>,<hostName>. 

Example of usage: returnValue = GetHostByAddr( hostIPAddr )

GetHostByName(string)

Performs a DNS lookup on the passed host name.  Returns: a string formatted as <errorCode>,<ipAddress>. 

Example of usage: returnValue = GetHostByName( hostName )

GetLastError()

Retrieves the last error encountered by a SFSockets method.  Call this when a method returns a non-zero error code  Returns: a Palm OS error code indicating the most recent error. 

Example of usage: err = GetLastError()

GetRecvTimeout()

Retrieves timeout value for Receive operations.  Returns: the current timeout period for Receive operations. 

Example of usage: timeout = GetRecvTimeout()

GetSendTimeout()

Retrieves timeout value for Send operations.  Returns: the current timeout period for Send operations. 

Example of usage: timeout = GetSendTimeout()

GetServiceByName(string, string)

Attempts to return the port number associated with a specified service. 

Example of usage: portNumber = GetServiceByName( serviceName, protocol ) where serviceName is one of the following:  'echo', 'discard', 'daytime', 'qotd', 'chargen', 'ftp-data', 'ftp', 'telnet', 'smtp', 'time', 'name', 'finger', 'pop2', 'pop3', 'nntp', 'imap2'.  Currently the only protocol you can use is 'tcp'.  Returns -1 to indicate an error.

GetSocketLinger(integer)

Gets the linger option for a socket.  Returns: a string formatted as <errorCode>,<lingerOn>,<lingerTime>. 

Example of usage: returnVal = GetSocketLinger( socketRef ), where 'socketRef' is a valid socket reference.

OpenNetLib()

Opens the net library.  Returns: zero for success, non-zero for an error condition. 

Example of usage: err = OpenNetLib()

OpenNetworkPrefPanel()

Opens the standard Network Preference panel.

Receive(integer, string, integer)

Receives data from a socket in one of two modes - either a defined number of characters, or up til a specified character.  Returns: a string formatted as <errCode>,<dataLen>,<data>. 

Example of usage: data = Receive( socketRef, termChar, numToRead ), where 'socketRef' is a valid socket reference, 'termChar' is the character to terminated the receive on, and 'numToRead' is the number of characters to read. You can only specify one of either 'termChar' or 'numToRead' - the other must be -1.

Send(integer, string)

Sends data to a socket.  Returns: either the number of bytes sent (>0), 0 indicating the socket was shutdown or -1 for an error condition. 

Example of usage: sent = Send( socketRef, data ), where 'socketRef' is a valid socket reference and data is a string containing the data you want to send.

SetRecvTimeout(integer)

Sets timeout value for Receive operations.  Returns: nothing. 

Example of usage: SetRecvTimeout( newValue ), where 'newValue' indicates the number of seconds before the timeout.

SetDomainName(string)

Sets the default domain name added to names before DNS lookups occur.

SetSendTimeout(integer)

Sets timeout value for Send operations.  Returns: nothing 

Example of usage: SetSendTimeout( newValue ), where 'newValue' indicates the number of seconds for the timeout.

SetSocketLinger(integer, integer, integer)

Sets the linger option on a socket.  Returns: zero for success, non-zero for an error condition. 

Example of usage: err = SetSocketLinger( socketRef, lingerOn, lingerTime), where 'socketRef' is a valid socket reference, 'lingerOn' is either 1 or 0 indicating whether the socket should linger, and 'lingerTime' is the time in seconds that a socket should linger.

Shutdown(integer)

Shuts down a socket.  Returns: zero for success, non-zero for an error condition. 

Example of usage: err = Shutdown( socket )

SKT_GetErrorString(integer)

Convert the specified error to string. 

Example of usage:  SKT_GetErrorString(ErrorNumber)

SKT_SetAutoOffTime()

Resets the automatic sleep timer. 0 means do not sleep. Returns the previous value.

Socket()

Creates a new socket.  Returns: a socket reference or -1 indicating an error condition. 

Example of usage: socketRef = Socket()

DocID: 10136  DocDate: 2005-07-18