Contents > Library Reference > Networking

Networking

Objects for IP networking.

Objects and Structures

Socket Encapsulates a BSD-style socket.
SocketStream Exposes a Socket as a Stream.
Network Encapsulates general network settings and methods.

Additional Topics

Using Networking An overview of using the Networking objects.

Contents > Library Reference > Networking > Socket object

Socket

The Socket object encapsulates a BSD-style socket used for sending and receiving data over a network. See Using Networking for an overview.

Object Properties

string localAddr Gets the local address associated with this socket when connected.
string remoteAddr Get the remote address associated with this socket when connected.

Object Methods

int open(int family, int type, int protocol) Opens this socket for use with the specified family, type, and protocol.
int close() Closes this socket.
int accept(Socket newSocket) Accepts a connection.
int bind(string localAddr) Binds this socket to a particular local address and port.
int connect(string addr) Connects this socket to a remote address.
int listen(int backlog) Causes this socket to start listening.
int sends(string data) Sends a string to the remote node.
int send(void* pdata, string type, int count) Sends count blocks of data over the socket from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
int recvs(string* pdata) Receives a string from the remote node.
int recv(void* pdata, string type, int count) Reads count blocks of data from the socket into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
int shutdown(int dir) Shut down this socket in one or both directions.

Contents > Library Reference > Networking > SocketStream object

SocketStream

The SocketStream is derived from Stream, providing read/write access to a Socket. To use this object, create and open a Socket object, assign it to the socket property, then call the read and write methods on Stream.

Object Properties

Socket socket Sets the Socket object that this stream should read/write to.

Object Methods

bool read(void* pdata, string type, int count) Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
bool write(void* pdata, string type, int count) Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
bool readInt(int* pi) Read an int from the stream into the memory pointed to by pi.
bool writeInt(int i) Write an int to the stream.
bool readWord(int* pw) Read an 2-byte word from the stream into the memory pointed to by pw.
bool writeWord(int w) Write a 2-byte word to the stream.
bool readFloat(float* pf) Read a float from the stream into the memory pointed to by pf.
bool writeFloat(float f) Write a float to the stream.
bool readString(string* ps) Read a string from the stream into the memory pointed to by ps.
bool writeString(string s) Write a string to the stream.
bool readChar(char* pc) Read a char from the stream into the memory pointed to by pc.
bool writeChar(char c) Write a char to the stream.

Contents > Library Reference > Networking > Network object

Network

The Network object contains methods and properties for opening and closing the stack, performing DNS queries, and getting the local address and timeout settings. See Using Networking for an overview.

Object Properties

string localAddr Gets the local address of the device when connect.
int timeout Gets or sets the maximum wait time for network operations, expressed in system ticks. -1 implies infinite.

Object Methods

int open() Opens the networking stack and connects it to the network according to system settings.
void close() Closes the networking stack. The stack remains open for a short period in case another app will be using it. In most cases, this is the preferred way to close the stack.
void closei() Closes the networking stack immediately.
int getHostByName(string name, string* paddr) Looks up the given name using DNS, putting the resulting address in paddr.
int getHostByAddr(string addr, string* pname) Attempts to find a matching DNS name for the specified addr.

Contents > Library Reference > Networking > Socket object > open

Socket.open

int open(int family, int type, int protocol)

Parameters:

family address family
type socket type
protocol protocol

Return value: 0 if successful, error code otherwise

Opens this socket for use with the specified family, type, and protocol.

Note: Valid families are: netAfInet (Palm OS does not yet support IPv6). Valid types are: netSockStream (OrbC does not currently support UDP). Valid protocols are: netProtoIpTcp. See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > close

Socket.close

int close()

Return value: 0 if successful, error code otherwise

Closes this socket.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > accept

Socket.accept

int accept(Socket newSocket)

Parameters:

newSocket socket to associate with the new connection

Return value: 0 if successful, error code otherwise

Accepts a connection.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > bind

Socket.bind

int bind(string localAddr)

Parameters:

localAddr local address to bind to

Return value: 0 if successful, error code otherwise

Binds this socket to a particular local address and port.

Note: The application only needs to specify a port, which can be done with a string like ":1234". See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > connect

Socket.connect

int connect(string addr)

Parameters:

addr remote address to connect to

Return value: 0 if successful, error code otherwise

Connects this socket to a remote address.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > listen

Socket.listen

int listen(int backlog)

Parameters:

backlog size of pending cannot list

Return value: 0 if successful, error code otherwise

Causes this socket to start listening.

Note: Palm OS currently only supports 1 as the backlog parameter. See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > sends

Socket.sends

int sends(string data)

Parameters:

data string to send

Return value: 0 if successful, error code otherwise

Sends a string to the remote node.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > send

Socket.send

int send(void* pdata, string type, int count)

Parameters:

pdata data pointer
type format string
count format count

Return value: 0 if successful, error code otherwise

Sends count blocks of data over the socket from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > recvs

Socket.recvs

int recvs(string* pdata)

Parameters:

pdata string address of received data

Return value: 0 if successful, error code otherwise

Receives a string from the remote node.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > recv

Socket.recv

int recv(void* pdata, string type, int count)

Parameters:

pdata data pointer
type format string
count format count

Return value: 0 if successful, error code otherwise

Reads count blocks of data from the socket into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Socket object > shutdown

Socket.shutdown

int shutdown(int dir)

Parameters:

dir direction of shutdown

Return value: 0 if successful, error code otherwise

Shut down this socket in one or both directions.

Note: Valid directions are: netDirInput, netDirOuput, netDirBoth. See Using Networking for error codes.
Contents > Library Reference > Networking > SocketStream object > read

SocketStream.read

bool read(void* pdata, string type, int count)

Parameters:

pdata data pointer
type format string
count format count

Return value: true if all the data was read

Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.


Contents > Library Reference > Networking > SocketStream object > write

SocketStream.write

bool write(void* pdata, string type, int count)

Parameters:

pdata data pointer
type format string
count format count

Return value: true if all the data was written

Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.


Contents > Library Reference > Networking > SocketStream object > readInt

SocketStream.readInt

bool readInt(int* pi)

Parameters:

pi int pointer

Return value: true if successful

Read an int from the stream into the memory pointed to by pi.


Contents > Library Reference > Networking > SocketStream object > writeInt

SocketStream.writeInt

bool writeInt(int i)

Parameters:

i int to write

Return value: true if successful

Write an int to the stream.


Contents > Library Reference > Networking > SocketStream object > readWord

SocketStream.readWord

bool readWord(int* pw)

Parameters:

pw int pointer

Return value: true if successful

Read an 2-byte word from the stream into the memory pointed to by pw.


Contents > Library Reference > Networking > SocketStream object > writeWord

SocketStream.writeWord

bool writeWord(int w)

Parameters:

w word to write

Return value: true if successful

Write a 2-byte word to the stream.


Contents > Library Reference > Networking > SocketStream object > readFloat

SocketStream.readFloat

bool readFloat(float* pf)

Parameters:

pf float pointer

Return value: true if successful

Read a float from the stream into the memory pointed to by pf.


Contents > Library Reference > Networking > SocketStream object > writeFloat

SocketStream.writeFloat

bool writeFloat(float f)

Parameters:

f float to write

Return value: true if successful

Write a float to the stream.


Contents > Library Reference > Networking > SocketStream object > readString

SocketStream.readString

bool readString(string* ps)

Parameters:

ps string pointer

Return value: true if successful

Read a string from the stream into the memory pointed to by ps.


Contents > Library Reference > Networking > SocketStream object > writeString

SocketStream.writeString

bool writeString(string s)

Parameters:

s string to write

Return value: true if successful

Write a string to the stream.


Contents > Library Reference > Networking > SocketStream object > readChar

SocketStream.readChar

bool readChar(char* pc)

Parameters:

pc char pointer

Return value: true if successful

Read a char from the stream into the memory pointed to by pc.


Contents > Library Reference > Networking > SocketStream object > writeChar

SocketStream.writeChar

bool writeChar(char c)

Parameters:

c char to write

Return value: true if successful

Write a char to the stream.


Contents > Library Reference > Networking > Network object > open

Network.open

int open()

Return value: 0 if successful, error code otherwise

Opens the networking stack and connects it to the network according to system settings.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Network object > close

Network.close

void close()

Closes the networking stack. The stack remains open for a short period in case another app will be using it. In most cases, this is the preferred way to close the stack.


Contents > Library Reference > Networking > Network object > closei

Network.closei

void closei()

Closes the networking stack immediately.


Contents > Library Reference > Networking > Network object > getHostByName

Network.getHostByName

int getHostByName(string name, string* paddr)

Parameters:

name name to resolve
paddr string address of resolved address

Return value: 0 if successful, error code otherwise

Looks up the given name using DNS, putting the resulting address in paddr.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Network object > getHostByAddr

Network.getHostByAddr

int getHostByAddr(string addr, string* pname)

Parameters:

addr address to look up
pname string address of retreived name

Return value: 0 if successful, error code otherwise

Attempts to find a matching DNS name for the specified addr.

Note: See Using Networking for error codes.
Contents > Library Reference > Networking > Using Networking

Using Networking

OrbC exposes networking through objects based on BSD sockets. This article does not attempt to teach the use of BSD sockets, instead it describes what is unique to the Palm OS or OrbC implementation. OrbC support for networking is provided by the OrbNetwork native add-in. To use it, you must add the line below to your application's source code. If your application is not built standalone, you must also ensure that OrbNetwork.prc is installed on the device or emulator.

#include "add-ins/OrbNetwork.oc"

To use any of the networking methods, you must first call Network.open(), which initializes the network stack and attempts to connect to the configured network (e.g. wi-fi or PPP). OrbNetwork does not support the Palm VII or i705, since they do not use the standard network library.

The most obvious difference between BSD and OrbC sockets are the addresses. Rather than using SOCKADDR pointers, addresses are represented by strings. This makes coding a bit easier, and enables applications to use IPv6 without any code changes (once IPv6 becomes available on the Palm OS). An address string is a dotted IP address with optional port, such as:

"129.22.104.22:80"

An empty string is interpreted as the local address. Thus, when calling Socket.bind(), only a port needs to be specified:

":1234"

All Socket methods (and the DNS methods) have a timeout associated with them. This timeout value is globally set on the Network object.

OrbC networking currently only support stream-based sockets. All OrbC sockets are currently blocking.

The following error codes may be returned from the Network and Socket methods:

netErrInvalidAddrString netErrOther
netErrParamErr netErrNoMoreSockets
netErrOutOfResources netErrOutOfMemory
netErrSocketNotOpen netErrSocketBusy
netErrMessageTooBig netErrSocketNotConnected
netErrNoInterfaces netErrPortInUse
netErrQuietTimeNotElapsed netErrInternal
netErrTimeout netErrSocketAlreadyConnected
netErrSocketClosedByRemote netErrOutOfCmdBlocks
netErrWrongSocketType netErrSocketNotListening
netErrUnknownSetting netErrUnknownProtocol
netErrUnreachableDest netErrWouldBlock
netErrDNSNameTooLong netErrDNSBadName
netErrDNSBadArgs netErrDNSLabelTooLong
netErrDNSAllocationFailure netErrDNSTimeout
netErrDNSUnreachable netErrDNSFormat
netErrDNSServerFailure netErrDNSNonexistantName
netErrDNSNIY netErrDNSRefused
netErrDNSImpossible netErrDNSNoRRS
netErrDNSAborted netErrDNSBadProtocol
netErrDNSTruncated netErrDNSNoRecursion
netErrDNSIrrelevant netErrDNSNotInLocalCache
netErrDNSNoPort netErrIPCantFragment
netErrIPNoRoute netErrIPNoSrc
netErrIPNoDst netErrIPktOverflow
netErrTooManyTCPConnections netErrNoDNSServers
netErrInterfaceDown