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 |