Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

67    Network Utilities

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

This chapter describes network utilities provided in the module NetSocket.c. These utilities are convenience functions that you can use in place of net library functions in applications that use the net library. You can find NetSocket.c in the folder Libraries\Net\Src. (On Palm OS® 3.5, NetSocket.c is in the folder CodeWarrior Libraries\Comms\NetSocket\Src.)

The include file for the functions described in this chapter is <unix/sys_socket.h>. This header file is not included by any other Palm header file; you must explicitly include it in your code.

For more information on NetSocket.c and sys_socket.h, see the chapter "Network Communication" in the Palm OS Programmer's Companion, vol. II, Communications.

Network Utility Functions ^TOP^

NetUReadN Function ^TOP^

Purpose

Reads a specified number of bytes from a socket.

Declared In

unix/sys_socket.h

Prototype

Int32 NetUReadN (
   NetSocketRef fd,
   UInt8 *bufP,
   UInt32 numBytes
)

Parameters

fd
Descriptor for the open socket.
bufP
Pointer to buffer to hold received data.
numBytes
Number of bytes to read.

Returns

Returns the number of bytes actually read. If the return value is less than 0, an error occurred.

Comments

This function repeatedly calls NetLibReceive() until numBytes have been read or until NetLibReceive returns an error.

See Also

NetUWriteN()

NetUTCPOpen Function ^TOP^

Purpose

Opens a TCP (streams-based) socket and connects it to a server.

Declared In

unix/sys_socket.h

Prototype

NetSocketRef NetUTCPOpen (
   Char *hostName,
   Char *serviceName,
   Int16 port
)

Parameters

hostName
Remote host, given either by name or by dotted decimal address.
serviceName
The name of a network service. Possible services are "echo", "discard", "daytime", "qotd", "chargen", "ftp-data", "ftp", "telnet", "smtp", "time", "name", "finger", "pop2", "pop3", "nntp", "imap2". The value of this parameter is ignored if the port parameter is greater than zero.
port
The number of the port to connect to on the remote host. Set port to zero to use serviceName instead.

Returns

Returns the socket descriptor of the socket that was connected, or -1 if an error occurred.

Comments

If serviceName is given and port is less than or equal to zero, this function looks up the port number for that service on the remote host and uses it for the connection.

This function is the equivalent of calling NetLibSocketOpen() and NetLibSocketConnect() (or socket and connect).


NOTE: This function does not return specific reasons for failure if there is a failure. This function is not production-quality code. It is provided as a quick and dirty way of creating a connection and as sample code that can be used as a reference.

NetUWriteN Function ^TOP^

Purpose

Writes the specified number of bytes to a socket.

Declared In

unix/sys_socket.h

Prototype

Int32 NetUWriteN (
   NetSocketRef fd,
   UInt8 *bufP,
   UInt32 numBytes
)

Parameters

fd
Descriptor for the open socket.
bufP
Pointer to buffer to write.
numBytes
Number of bytes to write.

Returns

Returns the number of bytes actually sent. If the return value is less than 0, an error occurred.

Comments

This function repeatedly calls NetLibSend() until numBytes have been written or until NetLibSend returns an error.

See Also

NetUReadN