This chapter describes the API available in the net library and its Berkeley sockets equivalents. The header file NetMgr.h
declares the net library API. The chapter covers:
For more information on the net library, see the chapter "Network Communication" in the Palm OS Programmer's Companion, vol. II, Communications.
Net Library Data Structures
NetConfigNameType Struct
Purpose
The NetConfigNameType
structure defines a configuration name. A configuration is a specific set of values for the net library settings. Typically, users set up configurations and assign names to them using the Network preferences panel.
Prototype
typedef struct { Char name[netConfigNameSize]; } NetConfigNameType, NetConfigNamePtr;
name
is the configuration's name. The netConfigNameSize
constant is currently defined to be 32.
Compatibility
Supported only if 3.2 New Feature Set is present.
NetHostInfoBufType Struct
Purpose
The NetHostInfoBufType
struct contains information about a host. The NetHostInfoType
struct, which maps to the hostent
struct, points to fields in this struct for its information.
Prototype
typedef struct { NetHostInfoType hostInfo; Char name[netDNSMaxDomainName+1]; Char *aliasList[netDNSMaxAliases+1]; Char aliases[netDNSMaxAliases] [netDNSMaxAliases+1]; NetIPAddr *addressList[netDNSMaxAddresses]; NetIPAddr address[netDNSMaxAddresses]; } NetHostInfoBufType, *NetHostInfoBufPtr;
Fields
-
hostInfo
- A
NetHostInfoType
struct, which maps to the Berkeley UNIX socketshostent
structure. -
name
- Official host name.
-
aliasList
-
aliases
- An array of aliases for the host name.
-
addressList
-
address
- An array of pointers to 32-bit IP addresses in host byte order.
NetHostInfoType Struct
Purpose
The NetHostInfoType
structure maps to the Berkeley UNIX sockets hostent
structure. It is defined as follows:
Prototype
typedef struct { Char *nameP; Char **nameAliasesP; UInt16 addrType; UInt16 addrLen; UInt8 **addrListP; } NetHostInfoType, *NetHostInfoPtr;
Fields
-
nameP
- Official host name.
-
nameAliasesP
- An array of aliases for the host name.
-
addrType
- The type of the return addresses. See
NetSocketAddrEnum
. -
addrLen
- The length in bytes of the return addresses.
-
addrListP
- An array of pointers to addresses in host byte order.
NetServInfoBufType Struct
Purpose
The NetServInfoBufType
struct contains information about a service. The NetServInfoType
struct, which maps to the servent
struct, points to fields in this struct for much of its information.
Prototype
struct { NetServInfoType servInfo; Char name[netServMaxName+1]; Char *aliasList[netServMaxAliases+1]; Char aliases[netServMaxAliases] [netServMaxName]; Char protoName[netProtoMaxName+1]; UInt8 reserved; } NetServInfoBufType, *NetServInfoBufPtr;
Fields
-
servInfo
- A
NetServInfoType
struct, which maps to the Berkeley UNIX socketsservent
structure. -
name
- Official name of the service
-
aliasList
-
aliases
- Array of aliases for the service name.
-
protoName
- Name of the protocol to use.
-
reserved
- Reserved for future use.
NetServInfoType Struct
Purpose
The NetServInfoType
structure maps to the servent
structure in Berkeley UNIX sockets API. It contains information about a service.
Prototype
struct { Char *nameP; Char **nameAliasesP; UInt16 port; Char *protoP; } NetServInfoType, *NetServInfoPtr;
Fields
-
nameP
- Official name of the service
-
nameAliasesP
- Array of aliases for the service name.
-
port
- Port number for the service.
-
protoP
- Name of the protocol to use.
NetSocketAddrEnum Enum
Purpose
The NetSocketAddrEnum
enum specifies the address types supported by the net library.
Prototype
typedef enum { netSocketAddrRaw = 0, netSocketAddrINET = 2 } NetSocketAddrEnum
Fields
-
netSocketAddrRaw
- Raw address. Supported in Palm OS® version 3.0 and higher.
-
netSocketAddrINET
- IP address.
NetSocketAddrINType Struct
Purpose
The NetSocketAddrINType
struct holds an internet socket address, that is, a socket that uses one of the internet protocols. This structure directly maps to the BSD UNIX sockaddr_in
structure.
Prototype
typedef struct NetSocketAddrINType { Int16 family; UInt16 port; NetIPAddr addr; } NetSocketAddrINType;
Fields
-
family
- Address family in host byte order. This is either
netSocketAddrINET
ornetSocketAddrRaw
. -
port
- The port in network byte order.
-
addr
- The IP address in network byte order.
NetSocketAddrRawType Struct
Purpose
The NetSocketAddrRawType
structure holds a raw socket address.
Prototype
typedef struct NetSocketAddrRawType { Int16 family; UInt16 ifInstance; UInt32 ifCreator; } NetSocketAddrRawType;
Fields
-
family
- Address family in host byte order. This is either
netSocketAddrINET
ornetSocketAddrRaw
. -
ifInstance
- The instance number of the interface that the socket uses to send and receive data.
-
ifCreator
- The creator of the interface that the socket uses.
Compatibility
Raw sockets are supported in Palm OS version 3.0 and higher.
NetSocketAddrType Struct
Purpose
The NetSocketAddrType
structure holds a generic socket address. This struct can hold any type of address including Internet addresses. It directly maps to the BSD UNIX sockaddr
structure.
Note that this structure is the same size as NetSocketAddrINType
and NetSocketAddrRawType
. This means that one of those two structures can be used for parameters declared to be NetSocketAddrType
.
Prototype
typedef struct NetSocketAddrType { Int16 family; UInt8 data[14]; } NetSocketAddrType;
NetSocketNoticeType Struct
Purpose
The NetSocketNoticeType
structure specifies the socket state changes that your application wishes to register for and the means that Net Library should use to communicate with your application—for example, by notification.
When registering your application for a socket notice, call NetLibSocketOptionSet()
and pass in a pointer to a NetSocketNoticeType
structure.
Prototype
typedef struct NetSocketNoticeType { Int32 condition; NoticeTypeEnum type; union{ struct { UInt32 notifyType; }notify ... } notice; } NetSocketNoticeType;
Fields
-
condition
- Bitifield specifying what socket activity you wish to receive notices for—closing a socket, socket receiving TCP data, etc. Constants for the bits in this field are defined in
NetMgr.h. See
"Socket Notice Trigger Conditions." -
type
- How net library should communicate with your application. For instance,
netSocketNoticeNotify
indicates a socket notice that uses notifications (This is the only socket notice type supported in Palm OS Garnet version 5.4). Socket notice type values are defined inNoticeTypeEnum
. -
notice
- Union that contains a structure describing the socket notice. The structure is appropriate to the kind of socket notice, as specified in the
type
field. -
notify
- Structure describing the notification that the socket notice is sending to your application.
-
notifyType
- Socket notification constant that you defined for your application. It must be unique.
Compatibility
Implemented if 5.4 New Feature Set is present.
NetSocketRef Typedef
Purpose
The NetSocketRef
defines a socket descriptor. The socket descriptor is created and returned by NetLibSocketOpen()
. It is used in any function that requires access to a socket.
Prototype
typedef Int16 NetSocketRef
NetSocketTypeEnum Enum
Purpose
The NetSocketTypeEnum
enum specifies the available socket types.
Prototype
typedef enum { netSocketTypeStream=1, netSocketTypeDatagram=2, netSocketTypeRaw=3, netSocketTypeReliableMsg=4 } NetSocketTypeEnum
Constants
-
netSocketTypeStream
- Streams protocol over wireline.
-
netSocketTypeDatagram
- UDP protocol.
-
netSocketTypeRaw
- Raw mode.
Compatibility
Implemented if 5.4 New Feature Set is present.
NoticeTypeEnum Enum
Purpose
The NoticeTypeEnum
specifies the kind of socket notice that an application is registering for. It indicates by what means a change in socket state should be communicated to the application—for instance, by notifications. Use a NoticeTypeEnum
value for the type
field of NetSocketNoticeType
.
Prototype
typedef enum { netSocketNoticeNotify=1, netSocketNoticeEvent netSocketNoticeMailbox netSocketNoticeCallback netSocketNoticeWake } NoticeTypeEnum;
Constants
-
netSocketNoticeNotify
- Indicates that socket notice should use notifications to communicate with the application.
-
netSocketNoticeEvent
- Not supported in Palm OS Garnet version 5.4.
-
netSocketNoticeMailbox
- Not supported in Palm OS Garnet version 5.4.
-
netSocketNoticeCallback
- Not supported in Palm OS Garnet version 5.4.
-
netSocketNoticeWake
- Not supported in Palm OS Garnet version 5.4.
Compatibility
Implemented if 5.4 New Feature Set is present.
Net Library Constants
Configuration Aliases
A configuration is a set of specific values for the net library settings. The net library defines a set of built-in configuration aliases for common network setups. These aliases point to configurations instead of holding the actual values themselves. You can specify an alias anywhere in the API you would specify a configuration.
The constants listed here specify the alias names. Most of the net library API requires a configuration index rather than a name. Use NetLibConfigIndexFromName()
to obtain the alias's index from the name.
Constants
-
netCfgNameDefault
- The default configuration.
-
netCfgNameDefWireline
- The default configuration for wireline communications.
-
netCfgNameDefWireless
- The default configuration for wireless communications.
-
netCfgNameCTPWireline
- The default configuration for wireline communications through the Palm Web Clipping Proxy server.
-
netCfgNameCTPWireless
- The default configuration for wireless communications through the Palm Web Clipping Proxy server.
Comments
By default, netCfgNameDefault
points to the user's default configuration, and all other aliases point to netCfgNameDefault
except for netCfgNameCTPWireless
, which points to an private wireless configuration.
Compatibility
Supported on version 3.2 and later.
I/O Flags
The I/O flags specify special handling instructions to functions that send and receive data. You can OR these values together to specify more than one.
Constants
-
netIOFlagOutOfBand
- Process out-of-band data. Available for send calls only.
-
netIOFlagPeek
- Peek at incoming message without dequeuing it.
-
netIOFlagDontRoute
- Send without using routing. This constant is currently ignored.
Socket Notice Trigger Conditions
The socket notice trigger condition is a bitfield that identifies one or more of the state changes associated with a socket—for instance, closing a socket, a socket receiving TCP data, etc.
When you register to receive a socket notice, the bitfield is passed to NetLibSocketOptionSet()
in the condition
field of the NetSocketNoticeType
structure. When you receive a socket notification, the condition
field of the SysNotifyNetSocketType
structure contains this bitfield, which you read to determine what state changes the socket has undergone.
These constants are defined in NetMgr.h
as follows:
Constants
-
netSocketNoticeErr
- Socket error.
-
netSocketNoticeUDPReceive
- Socket received UDP data.
-
netSocketNoticeTCPReceive
- Socket received TCP data.
-
netSocketNoticeTCPTransmit
- Socket transmitted TCP data.
-
netSocketNoticeTCPRemoteClosed
- Remote TCP connection closed.
-
netSocketNoticeTCPClosed
- Local TCP connection closed.
-
netSocketNoticeConnectInbound
- A remote node tried to connect.
-
netSocketNoticeConnectOutbound
- Your application tried to connect to a remote node.
Comments
f you wish to receive notice of all socket conditions, use 0xFFFFFFFF
as the value of the condition
field .
Compatibility
Implemented if 5.4 New Feature Set is present.
Tracing Bits
The tracing bits are used to set the level of event tracing. An application can get a list of events in the trace buffer using the NetLibMaster()
call.
You can set the tracing for each network interface using NetLibIFSettingSet()
and for the net library in general with NetLibSettingSet()
.
Constants
-
netTracingErrors
- Record run-time errors. This is the default.
-
netTracingMsgs
- Record application trace messages.
-
netTracingPkts
- Record packet I/O. This bit is obsolete in versions 3.2 and higher, but is mapped to
netTracingPktIP
. -
netTracingFuncs
- Record function flow.
-
netTracingAppMsgs
- Record application messages sent using
NetLibTracePrintF()
andNetLibTracePutS()
. -
netTracingPktIP
- Record packet I/O. If this set, the following five options are enabled.
-
netTracingData40
- Record the first 40 bytes of each packet sent or received. This option is mutually exclusive with
netTracingData
. -
netTracingData
- Record the entirety of each packet sent or received. This option is mutually exclusive with
netTracingData40
. -
netTracingIFHi
- Record packets sent or received at the highest layer of the network interface. This layer is just below the IP layer.
-
netTracingIFMid
- Record packets sent or received at the layer just below the highest layer of the network interface.
-
netTracingIFLow
- Record packets sent or received at the lowest layer of the network interface.
Compatibility
The netTracingPktXXX
constants are supported only in version 3.2 devices and higher. In previous versions, specify netTracingPkts
instead; only the size of the packet is recorded.
Net Library Functions
NetHToNL Macro
Purpose
Converts a 32-bit value from host to network byte order.
Declared In
NetBitUtils.h
Prototype
#define NetHToNL ( x )
Parameters
Returns
Returns x
in network byte order.
Sockets Equivalent
See Also
NetNToHS()
, NetNToHL()
, NetHToNS()
NetHToNS Macro
Purpose
Converts a 16-bit value from host to network byte order.
Declared In
NetBitUtils.h
Prototype
#define NetHToNS ( x )
Parameters
Returns
Returns x
in network byte order.
Sockets Equivalent
See Also
NetNToHS()
, NetNToHL()
, NetHToNL()
NetLibAddrAToIN Function
Purpose
Converts an ASCII string representing a dotted decimal IP address into a 32-bit IP address in network byte order.
Declared In
NetMgr.h
Prototype
NetIPAddr NetLibAddrAToIN ( UInt16 libRefnum, const Char *a )
Parameters
Returns
Returns a 32-bit network byte order IP address or -1 if a
doesn't represent a dotted decimal IP address
Sockets Equivalent
See Also
NetLibAddrINToA Function
Purpose
Converts an IP address from 32-bit network byte order into a dotted decimal ASCII string.
Declared In
NetMgr.h
Prototype
Char *NetLibAddrINToA ( UInt16 libRefnum, NetIPAddr inet, Char *spaceP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
inet
- 32-bit IP address in network byte order.
-
←
spaceP
- Buffer used to hold the return value.
Returns
Returns in spaceP
the dotted decimal ASCII string representation of the IP address.
Sockets Equivalent
char *inet_ntoa (struct in_addr in)
See Also
NetLibClose Function
Purpose
Declared In
NetMgr.h
Prototype
Err NetLibClose ( UInt16 libRefnum, UInt16 immediate )
Parameters
-
→
libRefnum
- Reference number of the net library.
-
→
immediate
- If
true
, library will shut down immediately. Iffalse
, library will shut down only if close timer expires before anotherNetLibOpen()
is issued.
Returns
Returns one of the following values:
-
0
- Success.
-
netErrNotOpen
- Library was not open.
-
netErrStillOpen
- Not really an error; returned if library is still in use by another application.
Sockets Equivalent
Comments
Applications must call this function when they no longer need the net library. If the net library open count is greater than 1 before this call is made, the count is decremented and netErrStillOpen
is returned. If the open count was 1, the library takes the following action:
- If
immediate
istrue
, the library shuts down immediately. All network interfaces are brought down, the net protocol stack task is terminated, and all memory used by the net library is freed. - If
immediate
isfalse
, a close timer is created and this call returns immediately without actually bringing the net library down. Instead it leaves it up and running but marks it as in the "close-wait" state. It remains in this state until either the timer expires or anotherNetLibOpen
is issued. If the timer expires, the library is shut down. If anotherNetLibOpen
call is issued before the timer expires (possibly by another application), the timer is cancelled and the library is marked as fully open.
In most cases, you should pass false
for immediate
. This allows the user to quit one Internet application and launch another within a short period of time without having to wait through the process of closing down and then re-establishing dial-up network connections.
See Also
NetLibOpen()
, NetLibOpenCount()
NetLibConfigAliasGet Function
Purpose
Return the configuration that an alias points to.
Prototype
Err NetLibConfigAliasGet ( UInt16 refNum, UInt16 aliasIndex, UInt16 *indexP, Boolean *isAnotherAliasP )
Parameters
-
→
refNum
- Reference number of the net library.
-
→
aliasIndex
- Index of the alias.
-
←
indexP
- Index of the configuration pointed to by the alias.
-
←
isAnotherAliasP
-
true
ifindexP
is the index of another alias;false
ifindexP
specifies an actual configuration.
Returns
Returns one of the following values:
Sockets Equivalent
Comments
Use this routine to find out which configuration a built-in alias points to. See "Configuration Aliases" for a description of the built-in aliases.
Compatibility
Implemented only if 3.2 New Feature Set is present.
See Also
NetLibConfigAliasSet Function
Purpose
Set a built-in alias to point to a defined configuration.
Prototype
Err NetLibConfigAliasSet ( UInt16 refNum, UInt16 configIndex, UInt16 aliasToIndex )
Parameters
-
→
refNum
- Reference number of the net library.
-
→
configIndex
- Index of the built-in alias to be set.
-
→
aliasToIndex
- Index of the configuration to which the alias should point. You cannot set an alias to point to itself.
Returns
Returns one of the following values:
-
0
- Success.
-
netErrConfigCantPointToAlias
- The configuration at
aliasToIndex
is an alias that points to an alias. -
netErrConfigNotAlias
- The configuration at
configIndex
isn't an alias. -
netErrOutOfCmdBlocks
-
netErrParamErr
- The specified index is out of range or there's no configuration at the index.
Sockets Equivalent
Comments
This function is used by the Network preferences panel when the user edits a configuration. Your application can use it to associate any of the built-in aliases with a defined configuration.
The built-in aliases are typically set up as shown in Table 66.1. In this example, applications that specify a configuration index of 0 through 3 use a configuration that the user defines. Applications that use index 4 use a private configuration created by the network library.
An alias can point to another alias so long as the nesting level is only one deep. That is, if you point an alias to an alias, you'll receive an error if that alias in turn points to another alias. This eliminates the possibility that an alias never resolves to an actual configuration.
Compatibility
Implemented only if 3.2 New Feature Set is present.
See Also
NetLibConfigDelete Function
Purpose
Delete a configuration from the net library's configuration table.
Prototype
Err NetLibConfigDelete ( UInt16 refNum, UInt16 index )
Parameters
-
→
refNum
- Reference number of the net library.
-
→
index
- Index of the configuration to delete. You cannot delete one of the built-in aliases described in "
Configuration Aliases
."
Returns
Returns one of the following values:
Sockets Equivalent
Compatibility
Implemented only if 3.2 New Feature Set Set is present.
See Also
NetLibConfigIndexFromName Function
Purpose
Obtain a configuration's index given its name.
Prototype
Err NetLibConfigIndexFromName ( UInt16 refNum, NetConfigNamePtr nameP, UInt16 *indexP )
Parameters
-
→
refNum
- Reference number of the net library.
-
→
nameP
- Pointer to a configuration name. See
NetConfigNameType
. -
←
indexP
- The index of the configuration with the name
*nameP
.
Returns
Returns one of the following values:
Sockets Equivalent
Comments
This function returns the index of a configuration given its name. Your application should store the configuration's index rather than its name because a configuration's name can change.
If you pass the name of a built-in alias in nameP
, this function returns the index of the alias's entry in the configuration table; it does not return the index that the alias points to. For example, if the alias netCfgNameCTPWireless
is stored at index 4 and points to index 5, NetLibConfigIndexFromName
returns 4. If you want to obtain the index that an alias points to, use NetLibConfigAliasGet()
.
Compatibility
Implemented only if 3.2 New Feature Set is present.
See Also
NetLibConfigList Function
Purpose
Return a list of net library configuration names.
Prototype
Err NetLibConfigList ( UInt16 refNum, NetConfigNameType nameArray[], UInt16 *arrayEntriesP )
Parameters
-
→
refNum
- Reference number of the net library.
-
←
nameArray
- The list of defined configurations. See
NetConfigNameType
. -
↔
arrayEntriesP
- On entry, contains the number of elements in
nameArray
. On return, contains the number of elements innameArray
that were actually used. The Net Library currently returns up to 16 entries. If the array is not large enough to hold all the configuration names, this function returns only as many names as the array can hold.
Returns
Returns one of the following values:
Sockets Equivalent
Comments
Use this function to obtain a list of the names of defined network configurations and configuration aliases.
Users create specific configurations using the Network preferences panel and associate names with each configuration. This function returns the list of defined configurations.
In addition to user-defined configurations, this function also returns built-in configuration aliases and private configurations. The built-in configuration aliases are described in "Configuration Aliases
." Their actual names begin with a period (.). Private configurations have names that begin with an underscore (_).
IMPORTANT: If you present the list returned by this function to your application's users, you must first filter out names beginning with a period or an underscore. These names are for internal use only.
Your application should refer to a configuration by its index rather than its name because the name can be changed. To obtain the configuration's index from its name, use NetLibConfigIndexFromName()
.
Compatibility
Implemented only if 3.2 New Feature Set is present.
NetLibConfigMakeActive Function
Purpose
Makes the specified configuration current without opening the net library.
Prototype
Err NetLibConfigMakeActive ( UInt16 refNum, UInt16 configIndex )
Parameters
-
→
refNum
- Reference number of the net library.
-
→
configIndex
- Index of the configuration to use. An index of 0 refers to the default configuration as defined by the Network preferences panel.
Returns
Returns one of the following values:
Sockets Equivalent
Comments
This function is used mainly by the Network preferences panel when the user edits and saves network configurations. The Network preferences panel uses this function to make current the configuration the user wants to edit, set the settings appropriately, and then save the configuration using NetLibConfigSaveAs()
.
Use this routine to make a specific configuration the current configuration without opening the net library. You should not use it if the net library is already open.
Unlike NetLibOpenConfig()
, this routine does not save the current net library configuration so that it can be restored upon close.
Compatibility
Implemented only if 3.2 New Feature Set is present.
NetLibConfigRename Function
Purpose
Rename the specified configuration.
Prototype
Err NetLibConfigRename ( UInt16 refNum, UInt16 index, NetConfigNamePtr newNameP )
Parameters
-
→
refNum
- Reference number of the net library.
-
→
configIndex
- Index of the configuration to be renamed.
-
→
newNameP
- Pointer to the new name. See
NetConfigNameType
. The new name must not start with a period (.) or an underscore (_).
Returns
Returns one of the following values:
-
0
- Success.
-
netErrConfigBadName
- The new name begins with a period.
-
netErrConfigCantDelete
- The configuration at the specified index is a built-in alias or private configuration that cannot be renamed.
-
netErrOutOfCmdBlocks
-
netErrParamErr
- The specified index is out of range or there is no configuration at the index.
Sockets Equivalent
Comments
You cannot specify a name beginning with a period (.) or an underscore (_). Names beginning with a period are reserved for the built-in configuration aliases. Names beginning with an underscore are hidden configurations used internally by net library.
Compatibility
Implemented only if 3.2 New Feature Set is present.
NetLibConfigSaveAs Function
Purpose
Save the current net library settings as a configuration with the specified name.
Prototype
Err NetLibConfigSaveAs ( UInt16 refNum, NetConfigNamePtr nameP )
Parameters
-
→
refNum
- Reference number of the net library.
-
→
nameP
- Pointer to a name for the configuration. See
NetConfigNameType
. The name must not start with a period (.) or an underscore (_).
Returns
Returns one of the following values:
-
0
- Success.
-
netErrConfigBadName
- The specified name begins with a period or underscore.
-
netErrConfigTooMany
- Not enough space to add another configuration. The Net Library can hold up to 16 configuration.
Sockets Equivalent
Comments
If the name you specify already exists, its configuration is replaced with this configuration.
You cannot specify a name beginning with a period (.) or an underscore (_). Names beginning with a period are reserved for the built-in configuration aliases. Names beginning with an underscore are hidden configurations used internally by net library.
The net library assigns an index to this new configuration. The configuration's index remains constant, while its name may change. Use NetLibConfigIndexFromName()
to obtain the configuration's index.
Compatibility
Implemented only if 3.2 New Feature Set is present.
See Also
NetLibConfigDelete()
, NetLibConfigRename()
NetLibConnectionRefresh Function
Purpose
This routine is a convenience call for applications. It checks the status of all connections and optionally tries to open any that were closed.
Declared In
NetMgr.h
Prototype
Err NetLibConnectionRefresh ( UInt16 refNum, Boolean refresh, UInt8 *allInterfacesUpP, UInt16 *netIFErrP )
Parameters
-
→
refnum
- Reference number of the net library.
-
→
refresh
- If
true
, any connections that aren't currently open are opened. -
←
allInterfacesUpP
- Set to
true
if all connections are open. -
←
netIFErrP
- First error encountered when reopening connections that were closed. (See
NetLibIFUp()
for a list of possible values.)
Returns
-
Returns one of the following values:
-
0
- Success.
-
netErrBufTooSmall
-
netErrOutOfCmdBlocks
-
netErrNoInterfaces
Sockets Equivalent
Comments
This function determines whether a connection is up based on the internal status of the TCP/IP stack. To test the presence of a "physical connection" (phone line, modem, serial cable), a command should be sent once it's been determined that the logical connection is up. If the physical connection is broken, nothing returns and a timeout error eventually occurs.
NetLibDmReceive Function
Purpose
Receive data from a socket directly into a database record.
Declared In
NetMgr.h
Prototype
Int16 NetLibDmReceive ( UInt16 libRefNum, NetSocketRef socket, void *recordP, UInt32 recordOffset, UInt16 rcvLen, UInt16 flags, void *fromAddrP, UInt16 *fromLenP, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
←
recordP
- Pointer to beginning of record to receive data into. Must be locked for use.
-
→
recordOffset
- Offset from beginning of record to read data into.
-
→
rcvLen
- Maximum number of bytes to read.
-
→
flags
- One or more
netIOFlagxxx
flags. See "I/O Flags
." -
←
fromAddrP
- Pointer to buffer to hold address of sender (
a
NetSocketAddrType
struct). PassNULL
if you don't need sender information. -
↔
fromLenP
- On entry, size of
fromAddrP
buffer. On exit, actual size of returned address infromAddrP
. PassNULL
if you don't need sender information. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns the number of bytes successfully received. If the return value is 0, the socket has been shut down by the remote host. If the return value is -1, an error has occurred and errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrWouldBlock
-
netErrUserCancel
-
netErrOutOfMemory
Comments
This call behaves similarly to NetLibReceive()
but reads the data directly into a database record, which is normally write-protected. The caller must pass a pointer to the start of the record and an offset into the record of where to start the read.
NetLibFinishCloseWait Function
Purpose
Forces the net library to do a complete close if it's currently in the close-wait state.
Declared In
NetMgr.h
Prototype
Err NetLibFinishCloseWait ( UInt16 libRefnum )
Parameters
Returns
Sockets Equivalent
Comments
This call checks the current open state of the net library. If it's in the close-wait state (see NetLibClose()
), it forces the library to perform an immediate, complete close operation.
NetLibGetHostByAddr Function
Purpose
Looks up a host name given its IP address.
Declared In
NetMgr.h
Prototype
NetHostInfoPtr NetLibGetHostByAddr( UInt16 libRefNum, UInt8 *addrP, UInt16 len, UInt16 type, NetHostInfoBufPtr bufP, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
addrP
- IP address of host to lookup.
-
→
len
- Length, in bytes, of
*addrP
. -
→
type
- Type of
addrP
. SeeNetSocketAddrEnum
. -
←
bufP
- Pointer to a
NetHostInfoBufType
struct in which to store the results of the lookup. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is 0.
Returns
Returns a pointer to the NetHostInfoType
portion of bufP
that contains results of the lookup. If the return value is 0, an error has occurred, and errP
contains one of the following values:
-
0
- No error
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
n
etErrDNSNameTooLong
-
netErrDNSBadName
-
netErrDNSLabelTooLong
-
netErrDNSAllocationFailure
-
netErrDNSTimeout
-
netErrDNSUnreachable
-
netErrDNSFormat
-
netErrDNSServerFailure
-
netErrDNSNonexistantName
-
netErrDNSNIY
-
netErrDNSRefused
-
netErrDNSImpossible
-
netErrDNSNoRRS
-
netErrDNSAborted
-
netErrDNSBadProtocol
-
netErrDNSTruncated
-
netErrDNSNoRecursion
-
netErrDNSIrrelevant
-
netErrDNSNotInLocalCache
-
netErrDNSNoPort
Sockets Equivalent
struct hostent *gethostbyaddr (char *addr,
int len, int type);
Comments
This call queries the domain name server(s) to look up a host name given its IP address.
See Also
NetLibGetHostByName Function
Purpose
Looks up a host IP address given a host name.
Declared In
NetMgr.h
Prototype
NetHostInfoPtr NetLibGetHostByName( UInt16 libRefNum, const Char *nameP, NetHostInfoBufPtr bufP, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
nameP
- Name of host to look up.
-
←
bufP
- Pointer to a
NetHostInfoBufType
struct in which to store the results of the lookup. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is 0.
Returns
Returns a pointer to the NetHostInfoType
portion of bufP
, which contains results of the lookup. If the return value is 0, an error has occurred and errP
contains one of the following values:
-
0
- No error
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
n
etErrDNSNameTooLong
-
netErrDNSBadName
-
netErrDNSLabelTooLong
-
netErrDNSAllocationFailure
-
netErrDNSTimeout
-
netErrDNSUnreachable
-
netErrDNSFormat
-
netErrDNSServerFailure
-
netErrDNSNonexistantName
-
netErrDNSNIY
-
netErrDNSRefused
-
netErrDNSImpossible
-
netErrDNSNoRRS
-
netErrDNSAborted
-
netErrDNSBadProtocol
-
netErrDNSTruncated
-
netErrDNSNoRecursion
-
netErrDNSIrrelevant
-
netErrDNSNotInLocalCache
-
netErrDNSNoPort
Sockets Equivalent
struct hostent *gethostbyname (char *name);
Comments
-
→ This call first checks the local name IP address host table in the net library preferences. If the entry is not found, it then queries the domain name server(s).
See Also
NetLibGetHostByAddr()
, NetLibGetMailExchangeByName()
NetLibGetMailExchangeByName Function
Purpose
Looks up the name of a host to use for a given mail exchange.
Declared In
NetMgr.h
Prototype
Int16 NetLibGetMailExchangeByName( UInt16 libRefNum, Char *mailNameP, UInt16 maxEntries, Char hostNames[][255+1], UInt16 priorities[], Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
mailNameP
- Name of the mail exchange to look up.
-
→
maxEntries
- Maximum number of host names to return.
-
←
hostNames
- Array of character strings of length
255+1
. The host name results are stored in this array. This array must be able to hold at leastmaxEntries
host names. -
←
priorities
- Array of
Word
s. The priorities of each host name found are stored in this array. This array must be at leastmaxEntries
in length. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is less than 0.
Returns
Returns the number of entries successfully found. If the return value is a negative number, an error has occurred, and errP
contains one of the following values:
-
0
- No error
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrDNSNameTooLong
-
netErrDNSBadName
-
netErrDNSLabelTooLong
-
netErrDNSAllocationFailure
-
netErrDNSTimeout
-
netErrDNSUnreachable
-
netErrDNSFormat
-
netErrDNSServerFailure
-
netErrDNSNonexistantName
-
netErrDNSNIY
-
netErrDNSRefused
-
netErrDNSImpossible
-
netErrDNSNoRRS
-
netErrDNSAborted
-
netErrDNSBadProtocol
-
netErrDNSTruncated
-
netErrDNSNoRecursion
-
netErrDNSIrrelevant
-
netErrDNSNotInLocalCache
-
netErrDNSNoPort
Sockets Equivalent
Comments
This call looks up the name(s) of host(s) to use for sending an e-mail. The caller passes the name of the mail exchange in mailNameP
and gets back a list of host names to which the mail message can be sent.
See Also
NetLibGetHostByAddr()
, NetLibGetHostByName()
NetLibGetServByName Function
Purpose
Looks up the port number for a standard TCP/IP service, given the desired protocol.
Declared In
NetMgr.h
Prototype
NetServInfoPtr NetLibGetServByName( UInt16 libRefNum, const Char *servNameP, const Char *protoNameP, NetServInfoBufPtr bufP, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
servNameP
- Name of the service to look up. Possible services are "echo", "discard", "daytime", "qotd", "chargen", "ftp-data", "ftp", "telnet", "smtp", "time", "name", "finger", "pop2", "pop3", "nntp", "imap2".
-
→
protoNameP
- Desired protocol to use, either "udp" or "tcp".
-
←
bufP
- Pointer to a
NetServInfoBufType
struct in which to store the results of the lookup. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is 0.
Returns
Returns a pointer to the NetServInfoType
portion of bufP
that contains results of the lookup. If the return value is 0, and error has occurred and errP
contains one of the following values:
-
0
- No error
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrUnknownProtocol
-
netErrUnknownService
Sockets Equivalent
struct servent *getservbyname (char *addr,
char *proto);
Comments
This call is a convenience call for looking up a standard port number given the name of a service and the protocol to use.
See Also
NetLibIFAttach Function
Purpose
Attach a new network interface.
Declared In
NetMgr.h
Prototype
Err NetLibIFAttach ( UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, Int32 timeout )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
ifCreator
- Creator of interface to attach.
-
→
ifInstance
- Instance number of interface to attach. The instance number is one of the values returned by
NetLibIFGet()
. -
→
timeout
- Timeout in ticks; -1 means infinite timeout.
Returns
Returns one of the following values:
Sockets Equivalent
Comments
This call can be used to attach a new network interface to the net library. Network interfaces are self-contained databases of type 'neti'
. The ifCreator
parameter to this function is used to locate the network interface database of the given creator.
If the net library is already open when this call is made, the network interface's database will be located and then called to initialize itself and attach itself to the protocol stack in real time. If the net library is not open when this call is made, the creator and instance number of the interface are stored in the active configuration. You need to save the active configuration using NetLibConfigSaveAs()
if you want the interface to be initialized and attached to the stack the next time the net library is opened.
See Also
NetLibIFGet()
, NetLibIFDetach()
NetLibIFDetach Function
Purpose
Detach a network interface from the protocol stack.
Declared In
NetMgr.h
Prototype
Err NetLibIFDetach ( UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, Int32 timeout )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
ifCreator
- Creator of interface to detach.
-
→
ifInstance
- Instance number of interface to detach.
-
→
timeout
- Timeout in ticks; -1 means infinite timeout.
Returns
Returns one of the following values:
Sockets Equivalent
Comments
If the net library is already open when this call is made, the interface is brought down and detached from the protocol stack in real time. If the net library is not open when this call is made, the creator and instance number of the interface are removed from the active configuration. You need to save the active configuration using NetLibConfigSaveAs()
if you don't want the interface to be attached the next time the library is opened.
See Also
NetLibIFGet()
, NetLibIFAttach()
NetLibIFDown Function
Purpose
Bring an interface down and hang up a connection.
Declared In
NetMgr.h
Prototype
Err NetLibIFDown ( UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, Int32 timeout )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
ifCreator
- Creator of interface to attach.
-
→
ifInstance
- Instance number of interface to attach.
-
→
timeout
- Timeout in ticks; -1 means wait forever.
Returns
Returns one of the following values:
-
0
- Success.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrInterfaceNotFound
Sockets Equivalent
Comments
The net library must be open before this call can be made. For dial-up interfaces, this call terminates a connection and hangs up the modem if necessary.
NetLibClose()
automatically brings down any attached interfaces, so this routine doesn't normally have to be called.
If the interface is already down, this routine returns immediately with no error.
See Also
NetLibIFGet()
, NetLibIFAttach()
, NetLibIFDetach()
, NetLibIFUp()
NetLibIFGet Function
Purpose
Get the creator and instance number of an installed interface by index.
Declared In
NetMgr.h
Prototype
Err NetLibIFGet ( UInt16 libRefNum, UInt16 index, UInt32 *ifCreatorP, UInt16 *ifInstanceP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
index
- Index of the interface to get. Indices start at 0.
-
←
ifCreatorP
- The interface's creator.
-
←
ifInstanceP
- The interface's instance number.
Returns
Returns one of the following values:
Sockets Equivalent
Comments
To get a list of all installed interfaces, call this function with successively increasing indices starting from 0 until the error netErrInvalidInterface
is returned.
The ifCreator
and ifInstance
values returned from this call can then be used with the NetLibSettingGet()
call to get more information about that particular interface.
See Also
NetLibIFAttach()
, NetLibIFDetach()
, "Settings for Interface Selection
" in the Palm OS Programmer's Companion, vol. II, Communications
NetLibIFSettingGet Function
Purpose
Retrieves a network interface specific setting.
Declared In
NetMgr.h
Prototype
Err NetLibIFSettingGet ( UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, UInt16 setting, void *valueP, UInt16 *valueLenP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
ifCreator
- Creator of the network interface.
-
→
ifInstance
- Instance number of the network interface.
-
→
setting
- Setting to retrieve; one of the
NetIFSettingEnum
constants. -
←
valueP
- Space for return value of setting.
-
↔
valueLenP
- On entry, size of
valueP
. On exit, actual size of setting.
Returns
Returns one of the following values:
-
0
- Success.
-
netErrUnknownSetting
- Invalid setting constant.
-
netErrPrefNotFound
- No current value for setting.
-
netErrBufTooSmall
-
valueP
was too small to hold entire setting. Setting value was truncated to fit invalueP
. -
netErrUnimplemented
-
netErrInterfaceNotFound
-
netErrBufWrongSize
Sockets Equivalent
Comments
This call can be used to retrieve the current value of any network interface setting. The caller must pass a pointer to a buffer to hold the return value (valueP
), the size of the buffer (*valueLenP
), and the setting ID (setting
). The setting ID is one of the constants in the NetIFSettingEnum
type.
Some settings, such as the login script, are variable size. For these types of settings, you can obtain the actual size required for the buffer by passing 0 for *valueLenP
. The required size is returned in valueLenP
.
Table 66.2 lists the network interface settings and the size of each setting. Some are only applicable to certain types of interfaces. Settings not applicable to a specific interface can be safely ignored and not set to any particular value.
Use with |
||
Subnet mask for interface. Doesn't need to be specified for PPP or SLIP type connections. |
||
Broadcast address for interface. Doesn't need to be specified for PPP or SLIP type connections. |
||
User name. Only required if the login script uses the user name substitution escape sequence in it. Call |
||
Password. Only required if the login script uses the password substitution escape sequence in it. Call |
||
Authentication user name. Only required if the authentication protocol uses a different user name than the what's in the |
||
Authentication password. If "$" then the user will be prompted for the authentication password at connect time. Else, if 0 length, then the |
||
Service name. Used for display purposes while showing the connection progress dialog box. Call |
||
Login script. Only required if the particular service requires a login sequence. Call |
||
Connect log. Generally, this setting is just retrieved, not set. It contains a log of events from the most recent login. To clear this setting, call |
||
Maximum number of seconds of inactivity allowed. Set to 0 to ignore. |
||
Maximum delay, in seconds, allowed between each stage of connection establishment or login script line. Must be non-zero. |
||
If non-zero, negotiate for an IP address. If zero, the IP address specified in the |
||
If non-zero, enable VJ header compression. Default is |
||
Number of slots to use for VJ compression. Default is 4 for PPP and 16 for SLIP and CSLIP. More slots require more memory so it is best to keep this number to a minimum. |
||
Maximum transmission unit in octets. Currently not implemented in SLIP or PPP. |
||
Which serial communication port to use. Port 0 is the only port available on the device. |
||
If bit 0 is 1, use hardware handshaking on the serial port. Default is no hardware handshaking. |
||
If |
||
If |
||
Zero-terminated modem initialization string, not including the "AT". If not specified ( |
||
Zero-terminated modem phone number string. Only required if |
||
Number of times to re-dial modem when trying to establish a connection. Only required if |
||
A bitfield of various trace bits. See " An application can get a list of events in the trace buffer using the |
||
Read-only. The actual IP address that the interface ends up using. The login script execution engine stores the result of the "g" (get IP address) command here as does the PPP negotiation logic. |
||
Read-only. The IP address of the PPP server we're connected to. |
||
|
||
Specifies if the interface is in raw mode. The net library places an interface in raw mode when it is bound to a raw socket in the raw domain. Raw sockets are available in Palm OS version 3.0 and higher. |
||
Read-only. The version number of the network interface device driver. This setting is defined only if 5.1 New Feature Set is present. |
||
Read-only. The firmware version of the network interface device, if any. This setting is defined only if 5.1 New Feature Set is present. |
||
Read-only. Firmware date in seconds since midnight, January 1, 1904. This setting is defined only if 5.1 New Feature Set is present. |
||
Read-only. Indicates whether or not the interface supports IEEE 802.11 wireless networking. This setting is defined only if 5.1 New Feature Set is present. |
||
For IEEE 802.11 interfaces only. The ESS ID of the radio. This setting is defined only if 5.1 New Feature Set is present. |
||
Read-only. For IEEE 802.11 interfaces only. The BSS ID (MAC address) of the access point to which the radio is connected. This setting is defined only if 5.1 New Feature Set is present. |
||
Read-only. For IEEE 802.11 interfaces only. |
||
Read-only. For IEEE 802.11 interfaces with radios programmed for operation in Japan only. The MKK call sign. This setting is defined only if 5.1 New Feature Set is present. |
||
Read-only. For IEEE 802.11 interfaces only. The radio's country code, which the radio uses to check if it operates within a particular country's regulations. This setting is defined only if 5.1 New Feature Set is present. |
See Also
NetLibIFSettingSet()
, NetLibSettingGet()
, NetLibSettingSet()
, "Interface Specific Settings" in the Palm OS Programmer's Companion, vol. II, Communications
NetLibIFSettingSet Function
Purpose
Sets a network interface specific setting.
Declared In
NetMgr.h
Prototype
Err NetLibIFSettingSet ( UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, UInt16 setting, void *valueP, UInt16 valueLen )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
ifCreator
- Creator of the network interface.
-
→
ifInstance
- Instance number of the network interface.
-
→
setting
- The setting to set, one of the
NetIFSettingEnum
constants. See Table 66.2. -
→
valueP
- Space new value of setting.
-
→
valueLen
- Size of new setting.
Returns
Returns one of the following values:
-
0
- Success.
-
netErrUnknownSetting
- Invalid setting constant.
-
netErrPrefNotFound
- No current value for setting.
-
netErrUnimplemented
-
netErrInterfaceNotFound
-
netErrBufWrongSize
-
netErrReadOnlySetting
Sockets Equivalent
Comments
This call can be used to set the current value of any network interface setting. The caller must pass a pointer to a buffer which holds the new value (valueP
), the size of the buffer (valueLen
), and the setting ID (setting
).
See NetLibIFSettingGet()
for an explanation of each of the settings.
Of particular interest is the netIFSettingResetAll
setting, which, if used, resets all settings for the interface to their default values. When using this setting, valueP
and valueLen
are ignored.
See Also
NetLibIFSettingGet()
, NetLibSettingGet()
, NetLibSettingSet()
,
"Interface Specific Settings" in the Palm OS Programmer's Companion, vol. II, Communications
NetLibIFUp Function
Purpose
Bring an interface up and establish a connection.
Declared In
NetMgr.h
Prototype
Err NetLibIFUp ( UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
ifCreator
- Creator of interface to attach.
-
→
ifInstance
- Instance number of interface to attach.
Returns
Returns one of the following values:
-
0
- Success.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrInterfaceNotFound
-
netErrUserCancel
-
netErrBadScript
-
netErrPPPTimeout
-
netErrAuthFailure
-
netErrPPPAddressRefused
Sockets Equivalent
Comments
The net library must be open before this call can be made. For dial-up interfaces, this call will dial up the modem if necessary and run through the connect script to establish the connection.
If the interface is already up, this routine returns immediately with no error. This call doesn't take a timeout parameter because it relies on each interface to have its own established timeout setting.
See Also
NetLibIFGet()
, NetLibIFAttach()
, NetLibIFDetach()
, NetLibIFDown()
NetLibMaster Function
Purpose
Retrieves the network statistics, interface statistics, and the contents of the trace buffer.
Declared In
NetMgr.h
Prototype
Err NetLibMaster ( UInt16 libRefNum, UInt16 cmd, NetMasterPBPtr pbP, Int32 timeout )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
cmd
- Function to perform (
NetMasterEnum
type). The following commands are supported: -
netMasterInterfaceInfo
-
netMasterInterfaceStats
-
netMasterIPStats
-
netMasterICMPStats
-
netMasterUDPStats
-
netMasterTCPStats
-
netMasterTraceEventGet
-
↔
pbP
- Command parameter block.
-
→
timeout
- Timeout in ticks; -1 means wait forever.
Returns
Returns one of the following values:
-
0
- No error
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrUnimplemented
Sockets Equivalent
Comments
This call allows applications to get detailed information about the net library. This information is usually helpful in debugging network configuration problems.
This function takes a command word (cmd
) and parameter block pointer (pbP
) as arguments and returns its results in the parameter block on exit. Which values you must specify in the parameter block and which values are returned are specific to the command you specify.
netMasterInterfaceInfo
The pbP->interfaceInfo
struct specifies interface information.
netMasterInterfaceStats
The pbP->interfaceStats
structure specifies interface statistics.
netMasterIPStats
The pbP->ipStats
structure contains statistics about the IP protocol. See NetMgr.h
for a complete list of statistics returned.
netMasterICMPStats
The pbP->icmpStats
structure contains statistics about the ICMP protocol. See NetMgr.h
for a complete list of statistics returned.
netMasterUDPStats
The pbP->udpStats
structure contains statistics about the UDP protocol. See NetMgr.h
for a complete list of statistics returned.
netMasterTCPStats
The pbP->tcpStats
structure contains statistics about the TCP protocol. See NetMgr.h
for a complete list of statistics returned.
netMasterTraceEventGet
The pbP->traceEventGet
structure contains a trace event.
See Also
NetLibOpen Function
Purpose
Opens and initializes the net library.
Declared In
NetMgr.h
Prototype
Err NetLibOpen ( UInt16 libRefnum, UInt16 *netIFErrsP )
Parameters
-
→
libRefnum
- Reference number of the net library.
-
←
netIFErrsP
- First error encountered when bringing up network interfaces. (See
NetLibIFUp()
for a list of possible values.)
Returns
Returns one of the following values:
-
0
- No error.
-
netErrAlreadyOpen
- Not really an error; returned if library was already open and the open count was simply incremented.
-
n
etErrOutOfMemory
- Not enough memory available to open the library.
-
netErrNoInterfaces
- Incorrect setup.
-
netErrPrefNotFound
- Incorrect setup.
Comments
Applications must call this function before using the net library. If the net library was already open, NetLibOpen
increments its open count. Otherwise, it opens the library, initializes it, starts up the net protocol stack component of the library as a separate task, and brings up all attached network interfaces.
NetLibOpen
uses settings saved in the net library's preferences database during initialization. These settings include the interfaces to attach, the IP addresses, etc. It's assumed that these settings have been previously set up by a preference panel or equivalent so an application doesn't normally have to set them up before calling NetLibOpen
.
If any of the attached interfaces fails to come up, *netIFErrsP
will contain the error number of the first interface that encountered a problem.
Compatibility
NetLibOpen
behaves slightly differently in version 3.2 and later than it does in previous releases. In version 3.2 and later, NetLibOpen
calls NetLibOpenConfig()
specifying the default configuration. NetLibOpenConfig
reverts all settings to their saved, default values before opening the net library.
See Also
SysLibFind()
, NetLibClose()
, NetLibOpenCount()
NetLibOpenConfig Function
Purpose
Opens and initializes the net library with the specified configuration.
Prototype
Err NetLibOpenConfig ( UInt16 refNum, UInt16 configIndex, UInt32 openFlags, UInt16 *netIFErrP )
Parameters
-
→
refNum
- Reference number of the net library.
-
→
configIndex
- Index of the configuration to use. 0 means use the default configuration as defined in the Network preferences panel.
-
→
openFlags
- Not used. Pass 0 for this parameter.
-
←
netIFErrP
- Pointer to return error code for interfaces.
Returns
Returns one of the following values:
-
0
- No error.
-
memErrNotEnoughSpace
-
netErrAlreadyOpen
- Not really an error; returned if library was already open and the open count was simply incremented.
-
netErrAlreadyOpenWithAnotherConfig
- Another application has the net library open with a configuration that is incompatible with the one specified.
-
netErrBufTooSmall
-
netErrConfigAliasErr
- A configuration alias was specified, but the alias could not be resolved.
-
netErrConfigCantDelete
-
netErrConfigEmpty
- The configuration is not defined.
-
netErrConfigNotFound
- The specified configuration index is invalid.
-
netErrInterfaceNotFound
-
netErrOutOfCmdBlocks
-
n
etErrOutOfMemory
- Not enough memory available to open the library.
-
netErrNoInterfaces
- Incorrect setup.
-
netErrParamErr
-
netErrPrefNotFound
- Incorrect setup.
-
netErrTimeout
Sockets Equivalent
Comments
Use this routine instead of NetLibOpen()
when you want to open the net library with a non-default configuration. If the default net library configuration is not suitable for your application, you may use one of the built-in aliases to specify a configuration that is suitable (see "Configuration Aliases").
NetLibOpenConfig
tries to open the net library and initialize it with the specified configuration. If another application has the net library open with an incompatible configuration, it returns an error. If the net library is in the close-wait state, this function completely closes the net library and then reopens it using the new configuration. If the net library can be opened with the new configuration, NetLibOpenConfig
first saves the current configuration so that it can be restored when your application closes the net library.
Typically, applications use the NetLibConfigList()
function to obtain the list of available configurations and present this list to the user. Then they call NetLibConfigIndexFromName()
with the user's selection to get the index of the configuration that the user selected.
The constant netConfigIndexCurSettings
specifies the current configuration. You can specify netConfigIndexCurSettings
as the configIndex
for testing purposes.
Compatibility
Implemented only if 3.2 New Feature Set is present.
See Also
NetLibOpen()
, SysLibFind()
, NetLibClose()
, NetLibOpenCount()
NetLibOpenCount Function
Purpose
Retrieves the open count of the net library.
Declared In
NetMgr.h
Prototype
Err NetLibOpenCount ( UInt16 refNum, UInt16 *countP )
Parameters
-
→
refNum
- Reference number of the net library.
-
←
countP
- Contains the open count of the net library upon return.
Returns
Sockets Equivalent
Comments
This call will most likely only be used by the Network preferences panel. Most applications will simply call NetLibOpen()
unconditionally during startup and NetLibClose()
when they exit.
NetLibReceive Function
Purpose
Receive data from a socket into a single buffer.
Declared In
NetMgr.h
Prototype
Int16 NetLibReceive ( UInt16 libRefNum, NetSocketRef socket, void *bufP, UInt16 bufLen, UInt16 flags, void *fromAddrP, UInt16 *fromLenP, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
←
bufP
- Pointer to buffer to hold received data.
-
→
bufLen
- Length of
bufP
buffer. -
→
flags
- One or more
netIOFlagxxx
flags. See "I/O Flags
." -
←
fromAddrP
- Pointer to buffer to hold address of sender (a
NetSocketAddrType
). -
↔
fromLenP
- On entry, size of
fromAddrP
buffer. On exit, actual size of returned address infromAddrP
. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns the number of bytes successfully received. If the return value is 0, the socket has been shut down by the remote host. If the return value is -1, an error has occurred, and errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrWouldBlock
-
netErrUserCancel
Sockets Equivalent
int recvfrom (int socket, const void *bufP,
int bufLen, int flags, const void *fromAddrP,
int *fromLenP);
int recv (int socket, const void *bufP,
int bufLen, int flags);
int read (int socket, const void *bufP,
int bufLen);
Comments
For stream-based sockets, this call reads whatever bytes are available and returns the number of bytes actually read into the caller's buffer. If there is no data available, this call will block until at least one byte arrives, until the socket is shut down by the remote host, or until a timeout occurs.
For datagram-based sockets, this call reads a complete datagram and returns the number of bytes in the datagram. If the caller's buffer is not large enough to hold the entire datagram, the end of the datagram is discarded. If a datagram is not available, this call will block until one arrives, or until the call times out.
The data is read into a single buffer pointed to by bufP
.
See Also
NetLibReceive()
, NetLibDmReceive()
, NetUReadN
, NetLibSend()
, NetLibSendPB()
NetLibReceivePB Function
Purpose
Receive data from a socket into a multi-buffer gather-read array.
Declared In
NetMgr.h
Prototype
Int16 NetLibReceivePB ( UInt16 libRefNum, NetSocketRef socket, NetIOParamType *pbP, UInt16 flags, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
pbP
- Pointer to parameter block containing buffer info.
-
→
flags
- One or more
netIOFlagxxx
flags. See "I/O Flags
." -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns the number of bytes successfully received. Returns 0 if the socket has been shut down by the remote host. If the return value is -1, an error has occurred, and errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrWouldBlock
Sockets Equivalent
int recvmsg (int socket, const struct msghdr *pbP,
int flags);
Comments
The pbP
parameter is a pointer to a NetIOParamType
structure. NetIOParamType
is defined as follows:
Prototype
typedef struct { UInt8 *addrP; UInt16 addrLen; NetIOVecPtr iov; UInt16 iovLen; UInt8 *accessRights; UInt16 accessRightsLen; } NetIOParamType, *NetIOParamPtr;
Fields
-
addrP
- Address of sender, set by
NetLibReceivePB
. Set to 0 if you don't require this field. -
addrLen
- Length of
*addrP
. -
iov
- Array of buffers into which the data should be received.
NetIOVecPtr
is a pointer to aNetIOVecType
structure, which has two fields: -
iovLen
- Length of the
iov
array. -
accessRights
- Access rights. This field currently isn't used and should be set to 0.
-
accessRightsLen
- Length of the
*accessRights
. This field currently isn't used and should be set to 0.
For stream-based sockets, this call reads whatever bytes are available and returns the number of bytes actually read into the caller's buffer. If no data is available, this call will block until at least one byte arrives, until the socket is shut down by the remote host, or until a timeout occurs.
For datagram-based sockets, this call reads a complete datagram and returns the number of bytes in the datagram. If the caller's buffer is not large enough to hold the entire datagram, the end of the datagram is discarded. If a datagram is not available, this call will block until one arrives, or until the call times out.
The data is read into the gather-read array specified by the pbP->iov
array.
See Also
NetLibReceive()
, NetLibDmReceive()
, NetLibSend()
, NetLibSendPB()
NetLibSelect Function
Purpose
Blocks until I/O is ready on one or more descriptors, where a descriptor can represent socket input, socket output, or a user input event like a pen tap or key press.
Declared In
NetMgr.h
Prototype
Int16 NetLibSelect ( UInt16 libRefNum, UInt16 width, NetFDSetType *readFDs, NetFDSetType *writeFDs, NetFDSetType *exceptFDs, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
width
- Number of descriptor bits to check in the
readFDs
,writeFDs
, andexceptFDs
descriptor sets. -
↔
readFDs
- Pointer to 32-bit
NetFDSetType
containing set of bits representing descriptors to check for input. -
↔
writeFDs
- Pointer to 32-bit
NetFDSetType
containing set of bits representing descriptors to check for output. -
↔
exceptFDs
- Pointer to 32-bit
NetFDSetType
containing set of bits representing descriptors to check for exception conditions. This parameter is ignored. Upon return, its bits are always cleared. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns the sum total number of ready file descriptors in *readFDs
, *writeFDs
, and *exceptFDs
. Returns 0 upon timeout. If the return value is -1, an error has occurred, and errP
contains one of the following values:
-
0
- No error
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
Sockets Equivalent
int select (int width, fd_set *readfds,
fd_set *writefds, fd_set *exceptfds,
struct timeval *timeout);
Comments
This call blocks until one or more descriptors are ready for I/O. In the Palm OS environment, a descriptor is either a NetSocketRef
or the "stdin" descriptor, sysFileDescStdIn
. The sysFileDescStdIn
descriptor will be ready for input whenever a user event is available like a pen tap or key press.
The caller should set which bits in each descriptor set need to be checked by using the netFDZero
and netFDSet
macros. After this call returns, the macro netFDIsSet
can be used to determine which descriptors in each set are actually ready.
On exit, the total number of ready descriptors is returned and each descriptor set is updated with the appropriate bits set for each ready descriptor in that set.
The following example illustrates how to use this call to check for input on a socket or a user event:
Err err; NetSocketRef socket; NetFDSetType readFDs,writeFDs,exceptFDs; Int16 numFDs; UInt16 width; // Create the descriptor sets netFDZero(&readFDs); netFDZero(&writeFDs); netFDZero(&exceptFDs); netFDSet(sysFileDescStdIn, &readFDs); netFDSet(socket, &readFDs); // Calculate the max descriptor number and // use that +1 as the max width. // Alternatively, we could simply use the // constant netFDSetSize as the width which // is simpler but makes the NetLibSelect call // slightly slower. width = sysFileDescStdIn; if (socket > width) width = socket; // Wait for any one of the descriptors to be // ready. numFDs = NetLibSelect(AppNetRefnum, width+1, &readFDs, &writeFDs, &exceptFDs, AppNetTimeout, &err);
Also see the NetSample
example application in the Palm OS Examples
folder. The function CmdTelnet
in the file CmdTelnet.c
shows how to use the Berkeley sockets select
function and how to interpret the results.
See Also
NetLibSend Function
Purpose
Send data to a socket from a single buffer.
Declared In
NetMgr.h
Prototype
Int16 NetLibSend ( UInt16 libRefNum, NetSocketRef socket, void *bufP, UInt16 bufLen, UInt16 flags, void *toAddrP, UInt16 toLen, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
bufP
- Pointer to data to write.
-
→
bufLen
- Length of data to write
-
→
flags
- One or more
netIOFlagxxx
flags. See "I/O Flags
." -
→
toAddrP
- Address to send to (a pointer to a
NetSocketAddrType
), or 0. -
→
toLen
- Size of
toAddrP
buffer. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns the number of bytes successfully sent. Returns 0 if the socket has been shut down by the remote host. If the return value is -1, an error has occurred, and errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrMessageTooBig
-
netErrSocketNotConnected
-
netErrSocketClosedByRemote
-
netErrIPCantFragment
-
netErrIPNoRoute
-
netErrIPNoSrc
-
netErrIPNoDst
-
netErrIPktOverflow
-
netErrOutOfCmdBlocks
-
netErrOutOfPackets
-
netErrInterfaceNotFound
-
netErrInterfaceDown
-
netErrUnreachableDest
-
netErrNoMultiPktAddr
-
netErrWouldBlock
Sockets Equivalent
int sendto (int socket, const void *bufP,
int bufLen, int flags, const void *toAddrP,
int toLen);
int send (int socket, const void *bufP,
int bufLen, int flags);
int write (int socket, const void *bufP,
int bufLen,);
Comments
This call attempts to write data to the specified socket and returns the number of bytes actually sent, which may be less than or equal to the requested number of bytes. The data is passed in a single buffer that bufP
points to.
For datagram sockets, you must only send a single packet at a time. If the data is too large to fit in a single UDP packet (1536 bytes), no data is sent and -1 is returned.
The toAddrP
field applies only to datagram sockets without an existing connection. An error is returned if the datagram socket was previously connected and toAddrP
is specified. Stream-based sockets, by definition, must have a connection established with a remote host before data can be written. Raw sockets (supported in Palm OS version 3.0 and higher) must construct the entire IP header, including the destination address, before data can be sent; thus, the address is taken from the data to be sent.
If there isn't enough buffer space to send any data, this call will block until there is enough buffer space, or until a timeout.
NOTE: For stream-based sockets, this call may write only a portion of the desired data. It always returns the number of bytes actually written. Consequently, the caller should be prepared to call this routine repeatedly until the desired number of bytes have been written, or until it returns 0 or -1.
See Also
NetLibSendPB()
, NetUWriteN()
, NetLibReceive()
, NetLibReceivePB()
, NetLibDmReceive()
NetLibSendPB Function
Purpose
Send data to a socket from a scatter-write array.
Declared In
NetMgr.h
Prototype
Int16 NetLibSendPB ( UInt16 libRefNum, NetSocketRef socket, NetIOParamType *pbP, UInt16 flags, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
pbP
- Pointer to parameter block containing buffer info. See the description in
NetLibReceivePB()
. -
→
flags
- One or more
netIOFlagxxx
flags. See "I/O Flags
." -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns the number of bytes successfully sent. Returns 0 if the socket has been shut down by the remote host. If the return value is -1, an error has occurred, and errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrMessageTooBig
-
netErrSocketNotConnected
-
netErrSocketClosedByRemote
-
netErrIPCantFragment
-
netErrIPNoRoute
-
netErrIPNoSrc
-
netErrIPNoDst
-
netErrIPktOverflow
-
netErrOutOfCmdBlocks
-
netErrOutOfPackets
-
netErrInterfaceNotFound
-
netErrInterfaceDown
-
netErrUnreachableDest
-
netErrNoMultiPktAddr
-
netErrWouldBlock
Sockets Equivalent
int sendmsg (int socket, const struct msghdr *pbP,
int flags);
Comments
This call attempts to write data to the given socket and returns the number of bytes actually sent, which may be less than or equal to the requested number of bytes. The data is passed in the scatter-write array specified in the pbP
parameter block.
For datagram sockets, you must only send a single packet at a time. If the data is too large to fit in a single UDP packet, no data is sent and -1 is returned.
The toAddrP
field applies only to datagram sockets without an existing connection. An error is returned if the datagram socket was previously connected and toAddrP
is specified. Stream-based sockets, by definition, must have a connection established with a remote host before data can be written. Raw sockets (supported in Palm OS version 3.0 and higher) must construct the entire IP header, including the destination address, before data can be sent; thus, the address is taken from the data to be sent.
If there isn't enough buffer space to send any data, this call will block until there is space, or until a timeout.
NOTE: For stream-based sockets, this call may write only a portion of the desired data. It always returns the number of bytes actually written. Consequently, the caller should be prepared to call this routine repeatedly until the desired number of bytes have been written, or until it returns 0 or -1.
See Also
NetLibSend()
, NetLibReceive()
, NetLibReceivePB()
, NetLibDmReceive()
NetLibSettingGet Function
Purpose
Declared In
NetMgr.h
Prototype
Err NetLibSettingGet ( UInt16 libRefNum, UInt16 setting, void *valueP, UInt16 *valueLenP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
setting
- Setting to retrieve, one of the
NetSettingEnum
constants. -
←
valueP
- Space for return value of setting.
-
↔
valueLenP
- On entry, size of
valueP
. On exit, actual size of setting.
Returns
Returns one of the following values:
-
0
- Success.
-
netErrUnknownSetting
- Invalid setting constant
-
netErrPrefNotFound
- No current value for setting
-
netErrBufTooSmall
-
valueP
was too small to hold entire setting. Setting value was truncated to fit invalueP
. -
netErrBufWrongSize
Sockets Equivalent
Comments
This call retrieves the current value of any general setting. The caller must pass a pointer to a buffer to hold the return value (valueP
), the size of the buffer (*valueLenP
), and the setting ID (setting
). The setting ID is one of the NetSettingEnum
constants in the netSettingEnum
type.
Some settings, such as the host table, are variable size. For these types of settings, you can obtain the actual size required for the buffer by passing 0 for *valueLenP
. The required size is returned in valueLenP
.
Table 66.3 lists the general settings and the type of each setting.
Used for |
||
IP address of primary DNS server. This setting must be set to a non-zero IP address in order to support any of the name lookup calls. |
||
IP address of secondary DNS server. Set to 0 to have stack ignore this setting. |
||
IP address of default router. Default value is 0 which is appropriate for most implementations with only one attached interface (besides loopback). Packets with destination IP addresses that don't lie in the subnet of an attached interface will be sent to this router through the default interface specified by the |
||
Creator of the default network interface. Default value is 0, which is appropriate for most implementations. Packets with destination IP addresses that don't lie in the subnet of a directly attached interface are sent through this interface. If this setting is 0, the stack automatically makes the first non-loopback interface the default interface. |
||
Instance number of the default network interface. Packets with destination IP addresses that don't lie in the subnet of an attached interface are sent through the default interface. Default value is 0. |
||
A zero-terminated character string of 64 bytes or less containing the host name of this machine. This setting is not actually used by the stack. It's present mainly for informative purposes and to support the |
||
A zero-terminated character string of 256 bytes or less containing the default domain. This default domain name is appended to all host names before name lookups are performed. If the name is not found, the host name is looked up again without appending the domain name to it. To have the stack not use the domain name, call |
||
A null-terminated character string containing the host table. This table is consulted first before sending a DNS query to the DNS server(s). To have the stack not use a host table, call host.company.com A 111.222.333.444 |
||
The close-wait time in milliseconds. This setting must be specified. See the discussion of the |
||
A bitfield of various trace bits. See " |
||
Maximum trace buffer size in bytes. Setting this setting always clears the existing trace buffer. Default is 2 KB. |
||
Boolean value, default is |
See Also
NetLibSettingSet()
, NetLibIFSettingSet()
, NetLibIFSettingGet()
, NetLibMaster()
NetLibSettingSet Function
Purpose
Declared In
NetMgr.h
Prototype
Err NetLibSettingSet ( UInt16 libRefNum, UInt16 setting, void *valueP, UInt16 valueLen )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
setting
- Setting to set; one of the
NetSettingEnum
constants. See Table 66.3. -
→
valueP
- New value for the setting.
-
→
valueLen
- Size of new setting.
Returns
Returns one of the following values:
-
0
- Success.
-
netErrUnknownSetting
- Invalid setting constant.
-
netErrInvalidSettingSize
-
valueLen
was invalid for the given setting. -
netErrBufWrongSize
-
netErrReadOnlySetting
Sockets Equivalent
Comments
This call can be used to set the current value of any general setting. The caller must pass a pointer to a buffer which holds the new value (valueP
), the size of the buffer (valueLen
), and the setting ID (setting
). The setting ID is one of the netSettingXXX
constants in the NetSettingEnum
type.
If the net library is not open at the time this call is made, the setting is stored in the active configuration. You need to save the active configuration using NetLibConfigSaveAs()
if you want the new value of the setting to be used the next time the net library is opened.
See NetLibSettingGet()
for an explanation of each of the settings.
Of particular interest is the netSettingResetAll
setting, which, if used, will reset all general settings to their default values. When using this setting, valueP
and valueLen
are ignored.
See Also
NetLibSettingGet()
, NetLibSettingSet()
, NetLibIFSettingSet()
, NetLibMaster()
NetLibSocketAccept Function
Purpose
Accept a connection from a stream-based socket.
Declared In
NetMgr.h
Prototype
Int16 NetLibSocketAccept ( UInt16 libRefnum, NetSocketRef socket, NetSocketAddrType *sockAddrP, Int16 *addrLenP, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
←
sockAddrP
- Address of remote host is returned here.
-
↔
addrLenP
- On entry, length of
sockAddrP
buffer in bytes. On exit, length of returned address stored in *sockAddrP
. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns the NetSocketRef
of the new socket. If the return value is -1, an error has occurred, and errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrSocketNotConnected
-
netErrSocketClosedByRemote
-
netErrWrongSocketType
-
netErrSocketNotListening
-
netErrUnimplemented
Sockets Equivalent
int accept (int socket, void *sockAddrP,
int *addrLenP);
Comments
Accepts the next connection request from a remote client. This call is only applicable to stream-based sockets. Before calling NetLibSocketAccept
on a socket, a server application needs to:
- Open the socket (
NetLibSocketOpen()
). - Bind the socket to a local address (
NetLibSocketBind()
). - Set the maximum pending connection-request queue length (
NetLibSocketListen()
).
NetLibSocketAccept
will block until a successful connection request is obtained from a remote client. After a successful connection is made, this call returns with the address of the remote host in *sockAddrP
and the socket descriptor of a new socket as the return value. You then use the new socket to send and receive data.
See Also
NetLibSocketBind()
, NetLibSocketListen()
NetLibSocketAddr Function
Purpose
Returns the local and remote addresses currently associated with a socket.
Declared In
NetMgr.h
Prototype
Int16 NetLibSocketAddr ( UInt16 libRefnum, NetSocketRef socketRef, NetSocketAddrType *locAddrP, Int16 *locAddrLenP, NetSocketAddrType *remAddrP, Int16 *remAddrLenP, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socketRef
- Descriptor for the open socket.
-
←
locAddrP
- Local address of socket is returned here.
-
↔
locAddrLenP
- On entry, length of
locAddrP
buffer in bytes. On exit, length of returned address stored in *locAddrP
. -
←
remAddrP
- Address of remote host is returned here.
-
↔
remAddrLenP
- On entry, length of
remAddrP
buffer in bytes. On exit, length of returned address stored in *remAddrP
. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns 0 upon success and -1 if an error occurred. If the return value is -1, errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrSocketClosedByRemote
-
netErrOutOfCmdBlocks
Sockets Equivalent
int getpeername (int s, struct sockaddr *name,
int *namelen);
int getsockname (int s, struct sockaddr *name,
int *namelen);
Comments
This call is mainly useful for stream-based sockets. It allows the caller to find out what address was bound to a connected socket and the address of the remote host that it's connected to.
In Palm OS version 3.0 and higher, if you pass a raw socket to this function, it returns the instance number and creator of the interface to which the socket is bound.
See Also
NetLibSocketBind()
, NetLibSocketConnect()
, NetLibSocketAccept()
NetLibSocketBind Function
Purpose
Assign a local address to a socket.
Declared In
NetMgr.h
Prototype
Int16 NetLibSocketBind ( UInt16 libRefnum, NetSocketRef socket, NetSocketAddrType *sockAddrP, Int16 addrLen, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
sockAddrP
- Pointer to the address to give to the socket. This can be a
NetSocketAddrINType
or aNetSocketAddrRawType
. -
→
addrLen
- Length of address in *
sockAddrP
. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns 0 upon success and -1 if an error occurred. If an error occurred, errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrSocketAlreadyConnected
-
netErrSocketClosedByRemote
-
netErrOutOfCmdBlocks
Sockets Equivalent
int bind (int socket, const void *sockAddrP,
int addrLen);
Comments
Applications that want to wait for an incoming connection request from a remote host must call this function. After calling NetLibSocketBind
, applications can call NetLibSocketListen()
and then NetLibSocketAccept()
to make the socket ready to accept connection requests.
Compatibility
Raw sockets are only supported in Palm OS version 3.0 and higher. See NetLibSocketOpen()
for instructions on how to bind raw sockets.
See Also
NetLibSocketConnect()
, NetLibSocketListen()
, NetLibSocketAccept()
NetLibSocketClose Function
Purpose
Declared In
NetMgr.h
Prototype
Int16 NetLibSocketClose ( UInt16 libRefnum, NetSocketRef socket, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns 0 upon success and -1 if an error occurred. If an error occurred, errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrOutOfCmdBlocks
Sockets Equivalent
Comments
Closes down a socket and frees all memory associated with it.
See Also
NetLibSocketOpen()
, NetLibSocketShutdown()
NetLibSocketConnect Function
Purpose
Assign a destination address to a socket and initiate three-way handshake if it's stream based.
Declared In
NetMgr.h
Prototype
Int16 NetLibSocketConnect ( UInt16 libRefnum, NetSocketRef socket, NetSocketAddrType *sockAddrP, Int16 addrLen, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
sockAddrP
- Pointer to address to connect to.
-
→
addrLen
- Length of address in *
sockAddrP.
-
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns 0 upon success and -1 if an error occurred. If an error occurred, errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrSocketBusy
-
netErrNoInterfaces
- Incorrect setup.
-
netErrPortInUse
-
netErrQuietTimeNotElapsed
-
netErrInternal
-
netErrSocketAlreadyConnected
-
netErrSocketClosedByRemote
-
netErrTooManyTCPConnections
-
netErrWouldBlock
-
netErrWrongSocketType
-
netErrOutOfCmdBlocks
Sockets Equivalent
int connect (int socket, const void *sockAddrP,
int addrLen);
See Also
NetLibSocketBind()
, NetUTCPOpen()
NetLibSocketListen Function
Purpose
Put a stream-based socket into passive listen mode.
Declared In
NetMgr.h
Prototype
Int16 NetLibSocketListen ( UInt16 libRefnum, NetSocketRef socket, UInt16 queueLen, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
queueLen
- Maximum number of pending connections allowed.
-
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns 0 upon success and -1 if an error occurred. If an error occurred, errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrOutOfResources
-
netErrSocketNotOpen
-
netErrSocketBusy
-
netErrNoInterfaces
- Incorrect setup.
-
netErrPortInUse
-
netErrInternal
-
netErrSocketAlreadyConnected
-
netErrSocketClosedByRemote
-
netErrWrongSocketType
-
netErrQuietTimeNotElapsed
-
netErrOutOfCmdBlocks
Sockets Equivalent
int listen (int socket, int queueLen);
Comments
Sets the maximum allowable length of the queue for pending connections. This call is only applicable to stream-based (TCP/IP) sockets.
After a socket is created and bound to a local address using NetLibSocketBind()
, a server application can call NetLibSocketListen
and then NetLibSocketAccept()
to accept connections from remote clients.
The queueLen
is currently quietly limited to 1 (higher values are ignored).
See Also
NetLibSocketBind()
, NetLibSocketAccept()
NetLibSocketOpen Function
Purpose
Declared In
NetMgr.h
Prototype
NetSocketRef NetLibSocketOpen ( UInt16 libRefnum, NetSocketAddrEnum domain, NetSocketTypeEnum type, Int16 protocol, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
domain
- Address domain. See
NetSocketAddrEnum
. -
→
type
- Desired type of connection. See
NetSocketTypeEnum
. -
→
protocol
- Protocol to use. This parameter is currently ignored.
- For raw sockets in the
netSocketAddrINET
domain, specify one of the following: - For all other socket types or for raw sockets in the raw domain, this parameter is ignored.
-
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns the NetSocketRef
of the opened socket or -1 if an error occurred. If an error occurred, errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrNoMoreSockets
-
netErrOutOfCmdBlocks
-
netErrOutOfMemory
Sockets Equivalent
int socket (int domain, int type, int protocol);
Comments
Allocates memory for a new socket and opens it.
Raw sockets are supported in Palm OS version 3.0 and higher. Two types of raw sockets are supported:
- Raw sockets in the
netSocketAddrINET
domainIn this case, you must bind the socket to an IP address using
NetLibSocketBind()
, passing aNetSocketAddrINType
structure for the socket address. The port field is ignored.For applications that use raw sockets in the INET domain, the net library checks the destination IP address of all incoming packets to see if it matches any of those raw sockets. If it does, the packet is enqueued directly into the matching socket and is not passed to the protocol stack.
When an application sends data through raw sockets in the IP domain, the net library packages the data into a packet and passes it directly to the interface's send routine. You are responsible for forming the entire IP header, including any necessary checksums, source and destination IP address, and so on.
- Raw sockets in the
netSocketAddrRaw
domain with no protocolIn this case, you must bind the socket to an interface using
NetLibSocketBind()
, passing aNetSocketAddrRawType
structure for the socket address. The instance and creator specify which interface the caller wants to receive raw packets from.When an interface is bound to a raw socket with no protocol, the net library places that interface into raw mode. In raw mode, the interface passes all incoming packets, no matter what the link layer protocol, to its raw receive function.
When an application sends data through a raw socket with no protocol, the net library packages the data into a packet and passes it directly to the interface's send routine.
The interface remains in raw mode until the raw socket is closed.
Compatibility
Raw sockets supported only in Palm OS version 3.0 and higher.
See Also
NetLibSocketClose()
, NetUTCPOpen()
NetLibSocketOptionGet Function
Purpose
Retrieves the current value of a socket option.
Declared In
NetMgr.h
Prototype
Int16 NetLibSocketOptionGet ( UInt16 libRefnum, NetSocketRef socket, UInt16 level, UInt16 option, void *optValueP, UInt16 *optValueLenP, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
level
- Level of the option, one of the
NetSocketOptLevelEnum
constants. SeeNetLibSocketOptionSet()
. -
→
option
- One of the
NetSocketOptEnum
constants. SeeNetLibSocketOptionSet()
. -
←
optValueP
- Pointer to variable holding new value of option.
-
↔
optValueLenP
- Size of variable pointed to by
optValueP
on entry. Actual size of return value on exit. -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns 0 upon success and -1 if an error occurred. If an error occurred, errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrUnimplemented
-
netErrWrongSocketType
-
netErrInvalidSettingSize
Sockets Equivalent
int getsockopt (int socket, int level, int option,
const void *optValueP, int *optValueLenP);
Comments
Returns the current value of a socket option. The caller passes a pointer to a variable to hold the returned value (in optValueP
) and the size of this variable (in *optValueLenP
). On exit, *optValueP
is updated with the actual size of the return value.
For all of the fixed size options (every option except netSocketOptIPOptions
), *optValueLenP
is unmodified on exit and this call does its best to return the value in the caller's desired type size.
For compatibility with existing Internet applications, this call is quite flexible on the *optValueLenP
parameter. If the desired type for an option is FLAG
, this call supports an *optValueLenP
of 1, 2, or 4. If the desired type for an option is int
, it supports an *optValueLenP
of 2 or 4.
See NetLibSocketOptionSet()
for a list of available options.
See Also
NetLibSocketOptionSet Function
Purpose
Declared In
NetMgr.h
Prototype
Int16 NetLibSocketOptionSet ( UInt16 libRefnum, NetSocketRef socket, UInt16 level, UInt16 option, void *optValueP, UInt16 optValueLen, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
level
- Level of the option, one of the
NetSocketOptLevelEnum
constants. See the comments section. -
→
option
- One of the
NetSocketOptEnum
constants. See the comments section. -
→
optValueP
- Pointer to the variable holding the new value of the option.
-
→
optValueLen
- Size of variable pointed to by
optValueP.
-
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns 0 upon success and -1 if an error occurred. If an error occurred, errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrUnimplemented
-
netErrWrongSocketType
-
netErrInvalidSettingSize
Sockets Equivalent
int setsockopt (int socketRef, int level,
int option, const void *optValueP,
int optValueLen);
Comments
Sets various options associated with a socket. The caller passes a pointer to the new option value in optValueP
and the size of the option in optValueLen
.
Table 66.4 lists the available options.
- The Level column specifies the option level, which is one of the
netSocketOptLevelXXX
constants. - The Option column lists the option, which is one of the
netSocketOptXXX
constants. - The G/S column lists whether this option can be fetched with the
NetLibSocketOptionGet()
call (G) and/or set (S) with this call. - The type column lists the data type of the option.
- The I column specifies whether or not this option is currently implemented.
For compatibility with existing Internet applications, this call is quite flexible on the optValueLen
parameter. If the desired type for an option is FLAG
, this call accepts an optValueLen
of 1, 2, or 4. If the desired type for an option is int
, it accepts an optValueLen
of 2 or 4.
Except for the netSocketOptSockNonBlocking
option, all options listed above have equivalents in the sockets API. The netSocketOptSockNonBlocking
option was added to this call in the net library in order to implement the functionality of the UNIX fcntl()
control call, which can be used to turn nonblocking mode on and off for sockets.
See Also
NetLibSocketShutdown Function
Purpose
Shut down a socket in one or both directions.
Declared In
NetMgr.h
Prototype
Int16 NetLibSocketShutdown ( UInt16 libRefnum, NetSocketRef socket, Int16 direction, Int32 timeout, Err *errP )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
socket
- Descriptor for the open socket.
-
→
direction
- Direction to shut down. One of the
NetSocketDirEnum
constants. Specifically: -
→
timeout
- Maximum timeout in system ticks; -1 means wait forever.
-
←
errP
- Contains an error code if the return value is -1.
Returns
Returns 0 upon success and -1 if an error occurred. If an error occurred, errP
contains one of the following values:
-
0
- No error.
-
netErrTimeout
- Call timed out.
-
netErrNotOpen
- The referenced net library has not been opened yet.
-
netErrParamErr
-
netErrSocketNotOpen
-
netErrNoMultiPktAddr
-
netErrOutOfCmdBlocks
Sockets Equivalent
int shutdown (int socket, int direction);
Comments
Shuts down communication in one or both directions on a socket.
If direction is netSocketDirInput
, the socket is marked as down in the receive direction and further read operations from it return a netErrSocketInputShutdown
error.
NetLibTracePrintF Function
Purpose
Store debugging information in the net library's trace buffer.
Declared In
NetMgr.h
Prototype
Err NetLibTracePrintF ( UInt16 libRefNum, const Char *formatStr, ... )
Parameters
-
→
libRefNum
- Reference number of the net library.
-
→
formatStr
- A
printf
style format string. -
→ ...
- Arguments to the format string.
Returns
Returns 0 upon success or netErrNotOpen
if the net library has not been opened.
Sockets Equivalent
Comments
This call is a convenient debugging tool for developing Internet applications. It stores a message into the net library's trace buffer, which can later be dumped using the NetLibMaster()
call. The net library's trace buffer is used to store run-time errors that the net library encounters as well as errors and messages from network interfaces and from applications that use this call.
The formatStr
parameter is a printf
style format string which supports the following format specifiers:
but it does not support field widths, leading 0's etc.
Note that the netTracingAppMsgs
bit of the netSettingTraceBits
setting must be set using the call NetLibSettingSet(...netSettingTraceBits...)
. Otherwise, this routine will do nothing.
See Also
NetLibTracePutS()
, NetLibMaster()
, NetLibSettingSet()
NetLibTracePutS Function
Purpose
Store debugging information in the net library's trace buffer.
Declared In
NetMgr.h
Prototype
Err NetLibTracePutS ( UInt16 libRefNum, Char *strP )
Parameters
Returns
Returns 0 upon success or netErrNotOpen
if the net library has not been opened.
Sockets Equivalent
Comments
This call is a convenient debugging tool for developing Internet applications. It will store a message into the net library's trace buffer which can later be dumped using the NetLibMaster()
call. The net library's trace buffer is used to store run-time errors that the net library encounters as well as errors and messages from network interfaces and from applications that use this call.
Note the netTracingAppMsgs
bit of the netSettingTraceBits
setting must be set using the NetLibSettingSet(...netSettingTraceBits...)
call or this routine will do nothing.
See Also
NetLibTracePrintF()
, NetLibMaster()
, NetLibSettingSet()
NetNToHL Macro
Purpose
Converts a 32-bit value from network to host byte order.
Declared In
NetBitUtils.h
Prototype
#define NetNToHL ( x )
Parameters
Returns
Errors
Sockets Equivalent
See Also
NetNToHS()
, NetHToNL()
, NetHToNS()
NetNToHS Macro
Purpose
Converts a 16-bit value from network to host byte order.
Declared In
NetBitUtils.h
Prototype
#define NetNToHS ( x )
Parameters
Returns
Errors
Sockets Equivalent
See Also
NetHToNL()
, NetNToHL()
, NetHToNS()