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

66    Net Library

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 ^TOP^

NetConfigNameType Struct ^TOP^

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 ^TOP^

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 {
NetHostInfoTypehostInfo;
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 sockets hostent 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 ^TOP^

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 ^TOP^

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 sockets servent 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 ^TOP^

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 ^TOP^

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 ^TOP^

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 or netSocketAddrRaw.
port
The port in network byte order.
addr
The IP address in network byte order.

NetSocketAddrRawType Struct ^TOP^

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 or netSocketAddrRaw.
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 ^TOP^

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 ^TOP^

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 in NoticeTypeEnum.
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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

Configuration Aliases ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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() and NetLibTracePutS().
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 ^TOP^

NetHToNL Macro ^TOP^

Purpose

Converts a 32-bit value from host to network byte order.

Declared In

NetBitUtils.h

Prototype

#define NetHToNL (
   x
)

Parameters

x
32-bit value to convert.

Returns

Returns x in network byte order.

Sockets Equivalent

htonl()

See Also

NetNToHS(), NetNToHL(), NetHToNS()

NetHToNS Macro ^TOP^

Purpose

Converts a 16-bit value from host to network byte order.

Declared In

NetBitUtils.h

Prototype

#define NetHToNS (
   x
)

Parameters

x
16-bit value to convert.

Returns

Returns x in network byte order.

Sockets Equivalent

htons()

See Also

NetNToHS(), NetNToHL(), NetHToNL()

NetLibAddrAToIN Function ^TOP^

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 (
   UInt16libRefnum,
   constChar*a
)

Parameters

libRefNum
Reference number of the net library.
a
Pointer to ASCII dotted decimal string.

Returns

Returns a 32-bit network byte order IP address or -1 if a doesn't represent a dotted decimal IP address

Sockets Equivalent

UInt32 inet_addr (char *cp)

See Also

NetLibAddrINToA()

NetLibAddrINToA Function ^TOP^

Purpose

Converts an IP address from 32-bit network byte order into a dotted decimal ASCII string.

Declared In

NetMgr.h

Prototype

Char *NetLibAddrINToA (
   UInt16libRefnum,
   NetIPAddrinet,
   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

NetLibAddrAToIN()

NetLibClose Function ^TOP^

Purpose

Closes the net library.

Declared In

NetMgr.h

Prototype

Err NetLibClose (
   UInt16libRefnum,
   UInt16immediate
)

Parameters

libRefnum
Reference number of the net library.
immediate
If true, library will shut down immediately. If false, library will shut down only if close timer expires before another NetLibOpen() 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

None.

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 is true, 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 is false, 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 another NetLibOpen is issued. If the timer expires, the library is shut down. If another NetLibOpen 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 ^TOP^

Purpose

Return the configuration that an alias points to.

Prototype

Err NetLibConfigAliasGet (
   UInt16refNum,
   UInt16aliasIndex,
   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 if indexP is the index of another alias; false if indexP specifies an actual configuration.

Returns

Returns one of the following values:

0
Success.
netErrConfigNotAlias
The configuration at aliasIndex is not an alias.

netErrOutOfCmdBlocks

netErrParamErr
The specified index is out of range or there is no configuration at the index.

Sockets Equivalent

None

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()

NetLibConfigAliasSet Function ^TOP^

Purpose

Set a built-in alias to point to a defined configuration.

Prototype

Err NetLibConfigAliasSet (
   UInt16refNum,
   UInt16configIndex,
   UInt16aliasToIndex
)

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

None

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.

Table 66.1  Example Configuration Table

Index

Name

Alias To

0

.Default

6

1

.DefWireline

0

2

.DefWireless

0

3

.CTPWireline

0

4

.CTPWireless

5

5

_RAMCTP

6

user-defined

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

NetLibConfigAliasGet()

NetLibConfigDelete Function ^TOP^

Purpose

Delete a configuration from the net library's configuration table.

Prototype

Err NetLibConfigDelete (
   UInt16refNum,
   UInt16index
)

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:

0
Success.
netErrConfigCantDelete
The configuration at index is a built-in alias.

netErrOutOfCmdBlocks

netErrParamErr
The specified index is out of range.

Sockets Equivalent

None

Compatibility

Implemented only if 3.2 New Feature Set Set is present.

See Also

NetLibConfigSaveAs()

NetLibConfigIndexFromName Function ^TOP^

Purpose

Obtain a configuration's index given its name.

Prototype

Err NetLibConfigIndexFromName (
   UInt16refNum,
   NetConfigNamePtrnameP,
   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:

0
Success.
netErrConfigNotFound
A configuration with the specified name could not be found.

netErrOutOfCmdBlocks

Sockets Equivalent

None

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()

NetLibConfigList Function ^TOP^

Purpose

Return a list of net library configuration names.

Prototype

Err NetLibConfigList (
   UInt16refNum,
   NetConfigNameTypenameArray[],
   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 in nameArray 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:

0
Success.
netErrOutOfCmdBlocks

Sockets Equivalent

None

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 ^TOP^

Purpose

Makes the specified configuration current without opening the net library.

Prototype

Err NetLibConfigMakeActive (
   UInt16refNum,
   UInt16configIndex
)

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:

0
Success.

netErrBufTooSmall

netErrConfigAliasErr

netErrConfigCantDelete

netErrConfigEmpty

netErrConfigNotFound

netErrOutOfCmdBlocks

netErrParamErr

netErrPrefNotFound

Sockets Equivalent

None

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 ^TOP^

Purpose

Rename the specified configuration.

Prototype

Err NetLibConfigRename (
   UInt16refNum,
   UInt16index,
   NetConfigNamePtrnewNameP
)

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

None

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 ^TOP^

Purpose

Save the current net library settings as a configuration with the specified name.

Prototype

Err NetLibConfigSaveAs (
   UInt16refNum,
   NetConfigNamePtrnameP
)

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.

netErrOutOfCmdBlocks

Sockets Equivalent

None

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 ^TOP^

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 (
   UInt16refNum,
   Booleanrefresh,
   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

None.

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 ^TOP^

Purpose

Receive data from a socket directly into a database record.

Declared In

NetMgr.h

Prototype

Int16 NetLibDmReceive (
   UInt16libRefNum,
   NetSocketRefsocket,
   void*recordP,
   UInt32recordOffset,
   UInt16rcvLen,
   UInt16flags,
   void*fromAddrP,
   UInt16*fromLenP,
   Int32timeout,
   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). Pass NULL if you don't need sender information.
fromLenP
On entry, size of fromAddrP buffer. On exit, actual size of returned address in fromAddrP. Pass NULL 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 ^TOP^

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 (
   UInt16libRefnum
)

Parameters

libRefnum
Reference number of the net library.

Returns

Returns one of the following values:
0
Success.
netErrTimeout

Sockets Equivalent

None.

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 ^TOP^

Purpose

Looks up a host name given its IP address.

Declared In

NetMgr.h

Prototype

NetHostInfoPtr NetLibGetHostByAddr(
   UInt16libRefNum,
   UInt8*addrP,
   UInt16len,
   UInt16type,
   NetHostInfoBufPtrbufP,
   Int32timeout,
   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. See NetSocketAddrEnum.
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.
netErrDNSNameTooLong
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,
intlen, int type);

Comments

This call queries the domain name server(s) to look up a host name given its IP address.

See Also

NetLibGetHostByName()

NetLibGetHostByName Function ^TOP^

Purpose

Looks up a host IP address given a host name.

Declared In

NetMgr.h

Prototype

NetHostInfoPtr NetLibGetHostByName(
   UInt16libRefNum,
   constChar*nameP,
   NetHostInfoBufPtrbufP,
   Int32timeout,
   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.
netErrDNSNameTooLong
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 ^TOP^

Purpose

Looks up the name of a host to use for a given mail exchange.

Declared In

NetMgr.h

Prototype

Int16 NetLibGetMailExchangeByName(
   UInt16libRefNum,
   Char*mailNameP,
   UInt16maxEntries,
    CharhostNames[][255+1],
   UInt16priorities[],
   Int32timeout,
   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 least maxEntries host names.
priorities
Array of Words. The priorities of each host name found are stored in this array. This array must be at least maxEntries 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

None

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 ^TOP^

Purpose

Looks up the port number for a standard TCP/IP service, given the desired protocol.

Declared In

NetMgr.h

Prototype

NetServInfoPtr NetLibGetServByName(
   UInt16libRefNum,
   constChar*servNameP,
   constChar*protoNameP,
   NetServInfoBufPtrbufP,
   Int32timeout,
   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

NetLibGetHostByName()

NetLibIFAttach Function ^TOP^

Purpose

Attach a new network interface.

Declared In

NetMgr.h

Prototype

Err NetLibIFAttach (
   UInt16libRefNum,
   UInt32ifCreator,
   UInt16ifInstance,
   Int32timeout
)

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:

0
Success.
netErrInterfaceNotFound
netErrTooManyInterfaces

Sockets Equivalent

None

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 ^TOP^

Purpose

Detach a network interface from the protocol stack.

Declared In

NetMgr.h

Prototype

Err NetLibIFDetach (
   UInt16libRefNum,
   UInt32ifCreator,
   UInt16ifInstance,
   Int32timeout
)

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:

0
Success.
netErrInterfaceNotFound

Sockets Equivalent

None

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 ^TOP^

Purpose

Bring an interface down and hang up a connection.

Declared In

NetMgr.h

Prototype

Err NetLibIFDown (
   UInt16libRefNum,
   UInt32ifCreator,
   UInt16ifInstance,
   Int32timeout
)

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

None

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 ^TOP^

Purpose

Get the creator and instance number of an installed interface by index.

Declared In

NetMgr.h

Prototype

Err NetLibIFGet (
   UInt16libRefNum,
   UInt16index,
   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:

0
Success.
netErrInvalidInterface
Index too high
netErrPrefNotFound
No current value for setting.

Sockets Equivalent

None

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 ^TOP^

Purpose

Retrieves a network interface specific setting.

Declared In

NetMgr.h

Prototype

Err NetLibIFSettingGet (
   UInt16libRefNum,
   UInt32ifCreator,
   UInt16ifInstance,
   UInt16setting,
   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 in valueP.
netErrUnimplemented
netErrInterfaceNotFound
netErrBufWrongSize

Sockets Equivalent

None

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.

Table 66.2  Network Interface Settings

netIFSetting...

Type

Description

ResetAll

void

Use with NetLibIFSettingSet() only. This clears all other settings for the interface to their default values.

Up

UInt8

Read-only. true if interface is currently up.

Name

Char[32]

Read-only. Name of this interface.

ReqIPAddr

UInt32

IP address of interface.

SubnetMask

UInt32

Subnet mask for interface. Doesn't need to be specified for PPP or SLIP type connections.

Broadcast

UInt32

Broadcast address for interface. Doesn't need to be specified for PPP or SLIP type connections.

Username

Char[32]

User name. Only required if the login script uses the user name substitution escape sequence in it. Call NetLibIFSettingSet() with a valueLen of 0 to remove this setting.

Password

Char[32]

Password. Only required if the login script uses the password substitution escape sequence in it. Call NetLibIFSettingSet() with a valueLen of 0 to remove this setting. If the login script uses password substitution and no password setting is set, the user will be prompted for a password at connect time.

AuthUsername

Char[32]

Authentication user name. Only required if the authentication protocol uses a different user name than the what's in the netIFSettingUsername setting. If this setting is empty (valueLen of 0), the Username setting will be used instead. Call NetLibIFSettingSet() with a valueLen of 0 to remove this setting.

AuthPassword

Char[32]

Authentication password. If "$" then the user will be prompted for the authentication password at connect time. Else, if 0 length, then the netIFSettingPassword setting or the result of its prompt will be used instead. Call NetLibIFSettingSet() with a valueLen of 0 to remove this setting.

ServiceName

Char[]

Service name. Used for display purposes while showing the connection progress dialog box. Call NetLibIFSettingSet() with a valueLen of 0 to remove this setting.

LoginScript

Char[]

Login script. Only required if the particular service requires a login sequence. Call NetLibIFSettingSet() with a valueLen of 0 to remove this setting. See below for a description of the login script format.

ConnectLog

Char[]

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 NetLibIFSettingSet() with a valueLen of 0.

InactivityTimeout

UInt16

Maximum number of seconds of inactivity allowed. Set to 0 to ignore.

EstablishmentTimeout

UInt16

Maximum delay, in seconds, allowed between each stage of connection establishment or login script line. Must be non-zero.

DynamicIP

UInt8

If non-zero, negotiate for an IP address. If zero, the IP address specified in the netIFSettingReqIPAddr setting will be used. Default is false.

VJCompEnable

UInt8

If non-zero, enable VJ header compression. Default is true for PPP, false for SLIP, and true for CSLIP.

VJCompSlots

UInt8

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.

MTU

UInt16

Maximum transmission unit in octets. Currently not implemented in SLIP or PPP.

AsyncCtlMap

UInt32

Bit mask of characters to escape for PPP. Default is 0.

PortNum

UInt16

Which serial communication port to use. Port 0 is the only port available on the device.

BaudRate

UInt32

Serial port baud rate to use in bits per second.

FlowControl

UInt8

If bit 0 is 1, use hardware handshaking on the serial port. Default is no hardware handshaking.

StopBits

UInt8

Number of stop bits. Default is 1.

ParityOn

UInt8

true if parity detection enabled. Default is false.

ParityEven

UInt8

true for even parity detection. Default is true.

UseModem

UInt8

If true, dial-up through modem. If false, go direct over serial port

PulseDial

UInt8

If true, pulse dial modem. Else, tone dial. Default is tone dial.

ModemInit

Char[]

Zero-terminated modem initialization string, not including the "AT". If not specified (valueLen of 0), the modem initialization string from system preferences are used.

ModemPhone

Char[]

Zero-terminated modem phone number string. Only required if netIFSettingUseModem is true.

RedialCount

UInt16

Number of times to re-dial modem when trying to establish a connection. Only required if netIFSettingUseModem is true.

DNSQuery

UInt8

true if PPP queries for DNS address. The default is true.

TraceBits

UInt32

A bitfield of various trace bits. See "Tracing Bits."

An application can get a list of events in the trace buffer using the NetLibMaster() call. Each interface has its own trace bits setting so that trace event recording in each interface can be selectively enabled or disabled.

ActualIPAddr

UInt32

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.

ServerIPAddr

UInt32

Read-only. The IP address of the PPP server we're connected to.

BringDownOnPowerDown

UInt8

true if the interface is brought down when the Palm OS device is turned off.

RawMode

UInt32

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.

DriverVersion

Char[20]

Read-only. The version number of the network interface device driver. This setting is defined only if 5.1 New Feature Set is present.

FirmwareVersion

Char[20]

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.

FirmwareDate

UInt32

Read-only. Firmware date in seconds since midnight, January 1, 1904. This setting is defined only if 5.1 New Feature Set is present.

80211Device

UInt8

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.

80211ESSID

Char[32]

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.

80211AccessPointBSSID

UInt8[6]

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.

80211AssociationStatus

UInt8

Read-only. For IEEE 802.11 interfaces only. true if the radio is associated. This setting is defined only if 5.1 New Feature Set is present.

80211MKKCallSign

Char[15]

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.

80211CountryText

Char[34]

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 ^TOP^

Purpose

Sets a network interface specific setting.

Declared In

NetMgr.h

Prototype

Err NetLibIFSettingSet (
   UInt16libRefNum,
   UInt32ifCreator,
   UInt16ifInstance,
   UInt16setting,
   void*valueP,
   UInt16valueLen
)

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

None

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 ^TOP^

Purpose

Bring an interface up and establish a connection.

Declared In

NetMgr.h

Prototype

Err NetLibIFUp (
   UInt16libRefNum,
   UInt32ifCreator,
   UInt16ifInstance
)

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

None

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 ^TOP^

Purpose

Retrieves the network statistics, interface statistics, and the contents of the trace buffer.

Declared In

NetMgr.h

Prototype

Err NetLibMaster (
   UInt16libRefNum,
   UInt16cmd,
   NetMasterPBPtrpbP,
   Int32timeout
)

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

None

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.

index

Index of interface to fetch info about.

creator

Creator of interface.

instance

Instance of interface.

netIFP

Private interface info pointer.

drvrName

Driver type that interface uses ("PPP", "SLIP", etc.).

hwName

Hardware driver name ("Serial Library", etc.).

localNetHdrLen

Number of bytes in local net header.

localNetTrailerLen

Number of bytes in local net trailer.

localNetMaxFrame

Local net maximum frame size.

ifName

Interface name with instance number concatenated.

driverUp

true if interface driver is up.

ifUp

true if interface media layer is up.

hwAddrLen

Length of interface's hardware address.

hwAddr

Interface's hardware address.

mtu

Maximum transfer unit of interface.

speed

Speed in bits per second.

lastStateChange

Time in milliseconds of last state change.

ipAddr

IP address of interface.

subnetMask

Subnet mask of local network.

broadcast

Broadcast address of local network.

netMasterInterfaceStats

The pbP->interfaceStats structure specifies interface statistics.

index

Index of interface to fetch info about.

inOctets

Number of octets received.

inUcastPkts

Number of packets received.

inNUcastPkts

Number of broadcast packets received.

inDiscards

Number of incoming packets that were discarded.

inErrors

Number of packet errors encountered.

inUnknownProtos

Number of unknown protocols encountered.

outOctets

Number octets sent.

outUcastPkts

Number of packets sent.

outNUcastPkts

Number of broadcast packets sent.

outDiscards

Number of packets discarded.

outErrors

Number of outbound packet errors.

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.

index

Index of event to fetch.

textP

Pointer to text string to return event in. Should be at least 256 bytes long.

See Also

NetLibSettingSet()

NetLibOpen Function ^TOP^

Purpose

Opens and initializes the net library.

Declared In

NetMgr.h

Prototype

Err NetLibOpen (
   UInt16libRefnum,
   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.
netErrOutOfMemory
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 ^TOP^

Purpose

Opens and initializes the net library with the specified configuration.

Prototype

Err NetLibOpenConfig (
   UInt16refNum,
   UInt16configIndex,
   UInt32openFlags,
   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
netErrOutOfMemory
Not enough memory available to open the library.
netErrNoInterfaces
Incorrect setup.
netErrParamErr
netErrPrefNotFound
Incorrect setup.
netErrTimeout

Sockets Equivalent

None

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 ^TOP^

Purpose

Retrieves the open count of the net library.

Declared In

NetMgr.h

Prototype

Err NetLibOpenCount (
   UInt16refNum,
   UInt16*countP
)

Parameters

refNum
Reference number of the net library.
countP
Contains the open count of the net library upon return.

Returns

Always returns 0.

Sockets Equivalent

None.

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 ^TOP^

Purpose

Receive data from a socket into a single buffer.

Declared In

NetMgr.h

Prototype

Int16 NetLibReceive (
   UInt16libRefNum,
   NetSocketRefsocket,
   void*bufP,
   UInt16bufLen,
   UInt16flags,
   void*fromAddrP,
   UInt16*fromLenP,
   Int32timeout,
   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 in fromAddrP.
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 (intsocket, constvoid*bufP,
intbufLen, intflags, constvoid*fromAddrP,
int*fromLenP);

int recv (intsocket, constvoid*bufP,
intbufLen, intflags);

int read (intsocket, constvoid*bufP,
intbufLen);

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 ^TOP^

Purpose

Receive data from a socket into a multi-buffer gather-read array.

Declared In

NetMgr.h

Prototype

Int16 NetLibReceivePB (
   UInt16libRefNum,
   NetSocketRefsocket,
   NetIOParamType*pbP,
   UInt16flags,
   Int32timeout,
   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 a NetIOVecType structure, which has two fields:
bufP
Pointer to a buffer.
bufLen
Length of bufP.
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 ^TOP^

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 (
   UInt16libRefNum,
   UInt16width,
   NetFDSetType*readFDs,
   NetFDSetType*writeFDs,
   NetFDSetType*exceptFDs,
   Int32timeout,
   Err*errP
)

Parameters

libRefNum
Reference number of the net library.
width
Number of descriptor bits to check in the readFDs, writeFDs, and exceptFDs 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,
structtimeval *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:


Errerr; 
NetSocketRefsocket; 
NetFDSetTypereadFDs,writeFDs,exceptFDs; 
Int16numFDs; 
UInt16width; 
 
// 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

NetLibSocketOptionSet()

NetLibSend Function ^TOP^

Purpose

Send data to a socket from a single buffer.

Declared In

NetMgr.h

Prototype

Int16 NetLibSend (
   UInt16 libRefNum,
   NetSocketRefsocket,
   void*bufP,
   UInt16bufLen,
   UInt16 flags,
   void*toAddrP,
   UInt16toLen,
   Int32timeout,
   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,
intbufLen, int flags, const void *toAddrP,
inttoLen);

int send (int socket, const void *bufP,
intbufLen, int flags);

int write (int socket, const void *bufP,
intbufLen,);

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 ^TOP^

Purpose

Send data to a socket from a scatter-write array.

Declared In

NetMgr.h

Prototype

Int16 NetLibSendPB (
   UInt16libRefNum,
   NetSocketRefsocket,
   NetIOParamType*pbP,
   UInt16flags,
   Int32timeout,
   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 ^TOP^

Purpose

Retrieves a general setting.

Declared In

NetMgr.h

Prototype

Err NetLibSettingGet (
   UInt16libRefNum,
   UInt16setting,
   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 in valueP.
netErrBufWrongSize

Sockets Equivalent

None

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.

Table 66.3  Net Library General Settings

netSetting...

Type

Description

ResetAll

void

Used for NetLibSettingSet() only. This will clear all other settings to their default values.

PrimaryDNS

UInt32

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.

SecondaryDNS

UInt32

IP address of secondary DNS server. Set to 0 to have stack ignore this setting.

DefaultRouter

UInt32

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 netSettingDefaultIFCreator/netSettingDefaultIFInstance pair.

DefaultIFCreator

UInt32

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.

DefaultIFInstance

UInt16

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.

HostName

Char[]

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 gethostname/sethostname sockets API calls. To clear the host name, call NetLibIFSettingSet() with a valueLen of 0.

DomainName

Char[]

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 NetLibIFSettingSet() with a valueLen of 0.

HostTbl

Char[]

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 NetLibIFSettingSet() with a valueLen of 0. The format of a host table is a series of lines separated by '\n' in the following format:

host.company.com A 111.222.333.444

CloseWaitTime

UInt32

The close-wait time in milliseconds. This setting must be specified. See the discussion of the NetLibClose() call for an explanation of the close-wait time.

TraceBits

UInt32

A bitfield of various trace bits. See "Tracing Bits." Default value is (netTracingErrors | netTracingAppMsgs). An application can get a list of events in the trace buffer using the NetLibMaster() call.

TraceSize

UInt32

Maximum trace buffer size in bytes. Setting this setting always clears the existing trace buffer. Default is 2 KB.

TraceRoll

UInt8

Boolean value, default is true (non-zero). If true, trace buffer will roll over when it fills. If false, tracing will stop as soon as trace buffer fills.

See Also

NetLibSettingSet(), NetLibIFSettingSet(), NetLibIFSettingGet(), NetLibMaster()

NetLibSettingSet Function ^TOP^

Purpose

Sets a general setting.

Declared In

NetMgr.h

Prototype

Err NetLibSettingSet (
   UInt16libRefNum,
   UInt16setting,
   void*valueP,
   UInt16valueLen
)

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

None

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 ^TOP^

Purpose

Accept a connection from a stream-based socket.

Declared In

NetMgr.h

Prototype

Int16 NetLibSocketAccept (
   UInt16libRefnum,
   NetSocketRefsocket,
   NetSocketAddrType*sockAddrP,
   Int16*addrLenP,
   Int32timeout,
   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:

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 ^TOP^

Purpose

Returns the local and remote addresses currently associated with a socket.

Declared In

NetMgr.h

Prototype

Int16 NetLibSocketAddr (
   UInt16libRefnum,
   NetSocketRefsocketRef,
   NetSocketAddrType*locAddrP,
   Int16*locAddrLenP,
   NetSocketAddrType*remAddrP,
   Int16*remAddrLenP,
   Int32timeout,
   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 ^TOP^

Purpose

Assign a local address to a socket.

Declared In

NetMgr.h

Prototype

Int16 NetLibSocketBind (
   UInt16libRefnum,
   NetSocketRefsocket,
   NetSocketAddrType*sockAddrP,
   Int16addrLen,
   Int32timeout,
   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 a NetSocketAddrRawType.
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,
intaddrLen);

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 ^TOP^

Purpose

Close a socket.

Declared In

NetMgr.h

Prototype

Int16 NetLibSocketClose (
   UInt16libRefnum,
   NetSocketRefsocket,
   Int32timeout,
   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

int close (int socket);

Comments

Closes down a socket and frees all memory associated with it.

See Also

NetLibSocketOpen(), NetLibSocketShutdown()

NetLibSocketConnect Function ^TOP^

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 (
   UInt16libRefnum,
   NetSocketRefsocket,
   NetSocketAddrType*sockAddrP,
   Int16addrLen,
   Int32timeout,
   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,
intaddrLen);

See Also

NetLibSocketBind(), NetUTCPOpen()

NetLibSocketListen Function ^TOP^

Purpose

Put a stream-based socket into passive listen mode.

Declared In

NetMgr.h

Prototype

Int16 NetLibSocketListen (
   UInt16libRefnum,
   NetSocketRefsocket,
   UInt16queueLen,
   Int32timeout,
   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 ^TOP^

Purpose

Open a new socket.

Declared In

NetMgr.h

Prototype

NetSocketRef NetLibSocketOpen (
   UInt16libRefnum,
   NetSocketAddrEnumdomain,
   NetSocketTypeEnumtype,
   Int16protocol,
   Int32timeout,
   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:
netSocketProtoIPTCP
netSocketProtoIPUDP
netSocketProtoIPRAW
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 domain

    In this case, you must bind the socket to an IP address using NetLibSocketBind(), passing a NetSocketAddrINType 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 protocol

    In this case, you must bind the socket to an interface using NetLibSocketBind(), passing a NetSocketAddrRawType 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 ^TOP^

Purpose

Retrieves the current value of a socket option.

Declared In

NetMgr.h

Prototype

Int16 NetLibSocketOptionGet (
   UInt16libRefnum,
   NetSocketRefsocket,
   UInt16level,
   UInt16option,
   void*optValueP,
   UInt16*optValueLenP,
   Int32timeout,
   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 NetLibSocketOptionSet().
option
One of the NetSocketOptEnum constants. See NetLibSocketOptionSet().
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()

NetLibSocketOptionSet Function ^TOP^

Purpose

Set a socket option.

Declared In

NetMgr.h

Prototype

Int16 NetLibSocketOptionSet (
   UInt16libRefnum,
   NetSocketRefsocket,
   UInt16level,
   UInt16option,
   void*optValueP,
   UInt16optValueLen,
   Int32timeout,
   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,
intoption, const void *optValueP,
intoptValueLen);

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.

Table 66.4  Net Library Socket Options

netSocket
OptLevel...


netSocketOpt...


G/S


Type


I


Description

IP

IPOptions

GS

UInt8[]

N

Options in IP Header

TCP

TCPNoDelay

GS

FLAG

Y

Don't delay send to coalesce packets

TCP

TCPMaxSeg

G

int

Y

Get TCP maximum segment size

Socket

SockDebug

GS

FLAG

N

Turn on recording of debug info

Socket

SockAcceptConn

G

FLAG

N

Socket has had listen

Socket

SockReuseAddr

GS

FLAG

N

Allow local address reuse

Socket

SockKeepAlive

GS

FLAG

Y

Keep connections alive

Socket

SockDontRoute

GS

FLAG

N

Just use interface addresses

Socket

SockBroadcast

GS

FLAG

N

Permit sending of broadcast messages

Socket

SockUseLoopback

GS

FLAG

N

Bypass hardware when possible

Socket

SockLinger

GS

NetSocketLingerType

Y

Linger on close if data present

NetSocketLingerType is a structure with two fields: onOff (true or false) and time (linger time in seconds).

Socket

SockOOBInLine

GS

FLAG

N

Leave received OOB data in-line

Socket

SockSndBufSize

GS

int

N

Send buffer size

Socket

SockRcvBufSize

GS

int

N

Receive buffer size

Socket

SockSndLowWater

GS

int

N

Send low-water mark

Socket

SockRcvLowWater

GS

int

N

Receive low-water mark

Socket

SockSndTimeout

GS

int

N

Send timeout

Socket

SockRcvTimeout

GS

int

N

Receive timeout

Socket

SockErrorStatus

G

int

Y

Get error status and clear

Socket

SockSocketType

G

int

Y

Get socket type

Socket

SockNonBlocking

GS

FLAG

Y

Set non-blocking mode on/off

Socket

SockNotice

S

NetSocketNoticeType

Y

Enable socket notices. Your application will receive a notice when certain socket conditions occur. Specify conditions you want to watch in the
optValueP->conditions field.

Socket

SockRequireErrClear

GS

FLAG

Y

Return the current error status for all subsequent socket function calls until the error is cleared.

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

NetLibSocketOptionGet()

NetLibSocketShutdown Function ^TOP^

Purpose

Shut down a socket in one or both directions.

Declared In

NetMgr.h

Prototype

Int16 NetLibSocketShutdown (
   UInt16libRefnum,
   NetSocketRefsocket,
   Int16direction,
   Int32timeout,
   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:
netSocketDirInput
netSocketDirOutput
netSocketDirBoth
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 ^TOP^

Purpose

Store debugging information in the net library's trace buffer.

Declared In

NetMgr.h

Prototype

Err NetLibTracePrintF (
   UInt16libRefNum,
   constChar*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

None

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:

%d, %i, %u, %x, %s, %c

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 ^TOP^

Purpose

Store debugging information in the net library's trace buffer.

Declared In

NetMgr.h

Prototype

Err NetLibTracePutS (
   UInt16libRefNum,
   Char*strP
)

Parameters

libRefNum
Reference number of the net library.
strP
String to store in the trace buffer.

Returns

Returns 0 upon success or netErrNotOpen if the net library has not been opened.

Sockets Equivalent

None

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 ^TOP^

Purpose

Converts a 32-bit value from network to host byte order.

Declared In

NetBitUtils.h

Prototype

#define NetNToHL (
   x
)

Parameters

x
32-bit value to convert.

Returns

Returns x in host byte order.

Errors

none

Sockets Equivalent

ntohl()

See Also

NetNToHS(), NetHToNL(), NetHToNS()

NetNToHS Macro ^TOP^

Purpose

Converts a 16-bit value from network to host byte order.

Declared In

NetBitUtils.h

Prototype

#define NetNToHS (
   x
)

Parameters

x
16-bit value to convert.

Returns

Returns x in host byte order.

Errors

None

Sockets Equivalent

ntohs()

See Also

NetHToNL(), NetNToHL(), NetHToNS()