This extension provides TCPIP Socket functions for PocketPC, equivalent to the Internet extension for PalmOS.

For a higher level implementation of the HTTP protocol, see SF-HTTP.

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.

WSAStartup

Initializes Winsock for use.

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

Usage: err = WSAStartup()

WSACleanup

De-initializes Winsock.

Usage: WSACleanup()

Socket

Creates a new socket.

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

Usage: socketRef = Socket()

Connect

Connects a socket to a specified address and port.

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

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.

Close

Closes a socket.

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

Usage: err = Close( socketRef ), where socketRef is a valid socket reference.

Send

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.

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

Receive

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>.

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.

[NOTE: In V1.0 of this extemsion the TermChar option is not implemented.]

Shutdown

Shutsdown a socket.

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

Usage: err = Shutdown( socket )

GetHostByName

Performs a DNS lookup on the passed host name.

Returns: a string formatted as <errorCode>,<ipAddress>.

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.

Usage: err = GetLastError()

SetSocketLinger

Sets the linger option on a socket.

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

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.

GetSocketLinger

Gets the linger option for a socket.

Returns: a string formatted as <errorCode>,<lingerOn>,<lingerTime>.

Usage: returnVal = GetSocketLinger( socketRef ), where socketRef is a valid socket reference.

GetHostByAddr

Performs a reverse DNS lookup on the passed IP address, returning the name of the host machine.

Returns: a string formatted as <errorCode>,<hostName>.

Usage: returnValue = GetHostByAddr( hostIPAddr )

DocID: 10137  DocDate: 2005-07-18