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 |