< Home < Developers < Development Support < Documentation

## 62 Net Library

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part III: Communications 62 Net Library Net Library Data Structures NetHostInfoBufType NetHostInfoType NetServInfoBufType NetServInfoType NetSocketAddrEnum NetSocketAddrINType NetSocketAddrRawType NetSocketAddrType NetSocketRef NetSocketTypeEnum Net Library Constants I/O Flags Tracing Bits Net Library Functions NetHToNL NetHToNS NetLibAddrAToIN NetLibAddrINToA NetLibClose NetLibConnectionRefresh NetLibDmReceive NetLibFinishCloseWait NetLibGetHostByAddr NetLibGetHostByName NetLibGetMailExchangeByName NetLibGetServByName NetLibIFAttach NetLibIFDetach NetLibIFDown NetLibIFGet NetLibIFSettingGet NetLibIFSettingSet NetLibIFUp NetLibMaster NetLibOpen NetLibOpenCount NetLibReceive NetLibReceivePB NetLibSelect NetLibSend NetLibSendPB NetLibSettingGet NetLibSettingSet NetLibSocketAccept NetLibSocketAddr NetLibSocketBind NetLibSocketClose NetLibSocketConnect NetLibSocketListen NetLibSocketOpen NetLibSocketOptionGet NetLibSocketOptionSet NetLibSocketShutdown NetLibTracePrintF NetLibTracePutS NetNToHL NetNToHS |  |  |  | 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: Net Library Data Structures Net Library Constants Net Library Functions For more information on the net library, see the chapter "Network Communication" in the Palm OS Programmer's Companion, vol. II, Communications. IMPORTANT: Applications cannot directly use the net library to make wireless connections. Use the INetLib for wireless connections. ## Net Library Data Structures ## NetHostInfoBufType 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.
    typedef struct {
      NetHostInfoType  hostInfo;
      Char         name[netDNSMaxDomainName+1];
      Char         *aliasList[netDNSMaxAliases+1];
      Char        aliases[netDNSMaxAliases]
                     [netDNSMaxAliases+1];
      NetIPAddr    *addressList[netDNSMaxAddresses];
      NetIPAddr    address[netDNSMaxAddresses];
    } NetHostInfoBufType, *NetHostInfoBufPtr;
#### Field Descriptions #####
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 The NetHostInfoType structure maps to the Berkeley UNIX sockets hostent structure. It is defined as follows:
    typedef struct {
      Char       *nameP;
      Char       **nameAliasesP;
      UInt16     addrType;
      UInt16     addrLen;
      UInt8      **addrListP;
    } NetHostInfoType, *NetHostInfoPtr;
#### Field Descriptions #####
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 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.
    struct {
      NetServInfoType servInfo;
      Char           name[netServMaxName+1];
      Char         *aliasList[netServMaxAliases+1];
      Char           aliases[netServMaxAliases]
    [netServMaxName];
      Char           protoName[netProtoMaxName+1];
      UInt8          reserved;
    } NetServInfoBufType, *NetServInfoBufPtr;
#### Field Descriptions #####
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 The NetServInfoType structure maps to the servent structure in Berkeley UNIX sockets API. It contains information about a service.
    struct {
      Char       *nameP;
      Char       **nameAliasesP;
      UInt16     port;
      Char       *protoP;
    } NetServInfoType, *NetServInfoPtr;
#### Field Descriptions #####
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 The NetSocketAddrEnum enum specifies the address types supported by the net library.
    typedef enum {
      netSocketAddrRaw = 0,
      netSocketAddrINET = 2
    } NetSocketAddrEnum
#### Value Descriptions #####
netSocketAddrRaw | Raw address. Supported in Palm OS® version 3.0 and higher.
netSocketAddrINET | IP address.
## NetSocketAddrINType 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.
    typedef struct NetSocketAddrINType {
      Int16      family;
      UInt16     port;
      NetIPAddr  addr;
    } NetSocketAddrINType;
#### Field Descriptions #####
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 The NetSocketAddrRawType structure holds a raw socket address.
    typedef struct NetSocketAddrRawType {
      Int16 family;
      UInt16 ifInstance;
      UInt32 ifCreator;
    } NetSocketAddrRawType;
#### Field Descriptions #####
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 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.
    typedef struct NetSocketAddrType {
      Int16 family;
      UInt8 data[14];
    } NetSocketAddrType;
## NetSocketRef 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.
    typedef Int16 NetSocketRef
## NetSocketTypeEnum The NetSocketTypeEnum enum specifies the available socket types.
    typedef enum {
      netSocketTypeStream=1,
      netSocketTypeDatagram=2,
      netSocketTypeRaw=3,
      netSocketTypeReliableMsg=4
    } NetSocketTypeEnum
#### Value Descriptions #####
netSocketTypeStream | Streams protocol over wireline.
netSocketTypeDatagram | UDP protocol.
netSocketTypeRaw | Raw mode.
## Net Library Constants ## I/O Flags The I/O flags specify special handling instructions to functions that send and receive data. You can OR these values together to specify more than one. ##### #####
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.
## Tracing Bits The tracing bits are used to set the level of event tracing. An application can get a list of events in the trace buffer using the NetLibMaster call. You can set the tracing for each network interface using NetLibIFSettingSet and for the net library in general with NetLibSettingSet. #####
netTracingErrors | Record run-time errors. This is the default.
netTracingMsgs | Record application trace messages.
netTracingPkts | Record packets I/O.
netTracingFuncs | Record function flow.
netTracingAppMsgs | Record application messages sent using NetLibTracePrintF and NetLibTracePutS.
## Net Library Functions ## NetHToNL #### Purpose Macro that converts a 32-bit value from host to network byte order. #### Prototype NetHToNL (x) #### Parameters #####
-> x | 32-bit value to convert.
#### Result Returns x in network byte order. #### Sockets Equivalent htonl() #### See Also NetNToHS, NetNToHL, NetHToNS ## NetHToNS #### Purpose Macro that converts a 16-bit value from host to network byte order. #### Prototype NetHToNS (x) #### Parameters #####
-> x | 16-bit value to convert.
#### Result Returns x in network byte order. #### Sockets Equivalent htons() #### See Also NetNToHS, NetNToHL, NetHToNL ## NetLibAddrAToIN #### Purpose Converts an ASCII string representing a dotted decimal IP address into a 32-bit IP address in network byte order. #### Prototype NetIPAddr NetLibAddrAToIN (UInt16 libRefnum, const Char *a) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> a | Pointer to ASCII dotted decimal string.
#### Result 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 #### Purpose Converts an IP address from 32-bit network byte order into a dotted decimal ASCII string. #### Prototype Char *NetLibAddrINToA (UInt16 libRefnum, NetIPAddr inet, Char *spaceP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> inet | 32-bit IP address in network byte order.
#####
<- spaceP | Buffer used to hold the return value.
#### Result 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 #### Purpose Closes the net library. #### Prototype Err NetLibClose (UInt16 libRefnum, UInt16 immediate) #### 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.
#### Result 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 ## NetLibConnectionRefresh #### 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. #### Prototype Err NetLibConnectionRefresh (UInt16 refNum, Boolean refresh, UInt8 *allInterfacesUpP, UInt16 *netIFErrP) #### Parameters #####
-> refnum | Reference number of the net library.
#####
-> refresh | If true, any connections that aren't currently open are opened.
#####
<- allInterfacesUpP | Set to true if all connections are open.
#####
<- netIFErrP | First error encountered when reopening connections that were closed. (See NetLibIFUp for a list of possible values.)
#### Result #####
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 #### Purpose Receive data from a socket directly into a database record. #### Prototype Int16 NetLibDmReceive (UInt16 libRefNum, NetSocketRef socket, void *recordP, UInt32 recordOffset, UInt16 rcvLen, UInt16 flags, void *fromAddrP, UInt16 *fromLenP, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
<- recordP | Pointer to beginning of record to receive data into. Must be locked for use.
#####
-> recordOffset | Offset from beginning of record to read data into.
#####
-> rcvLen | Maximum number of bytes to read.
#####
-> flags | One or more netIOFlagxxx flags. See "I/O Flags."
#####
<- fromAddrP | Pointer to buffer to hold address of sender (a NetSocketAddrType struct). 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.
#### Result 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 #### Purpose Forces the net library to do a complete close if it's currently in the close-wait state. #### Prototype Err NetLibFinishCloseWait (UInt16 libRefnum) #### Parameters #####
-> libRefnum | Reference number of the net library.
#### Result #####
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 #### Purpose Looks up a host name given its IP address. #### Prototype NetHostInfoPtr NetLibGetHostByAddr (UInt16 libRefNum, UInt8 *addrP, UInt16 len, UInt16 type, NetHostInfoBufPtr bufP, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> addrP | IP address of host to lookup.
#####
-> len | Length, in bytes, of *addrP.
#####
-> type | Type of addrP. 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.
#### Result 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, int len, int type); #### Comments This call queries the domain name server(s) to look up a host name given its IP address. #### See Also NetLibGetHostByName ## NetLibGetHostByName #### Purpose Looks up a host IP address given a host name. #### Prototype NetHostInfoPtr NetLibGetHostByName (UInt16 libRefNum, const Char *nameP, NetHostInfoBufPtr bufP, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> nameP | Name of host to look up.
#####
<- bufP | Pointer to a NetHostInfoBufType struct in which to store the results of the lookup.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is 0.
#### Result 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 #### Purpose Looks up the name of a host to use for a given mail exchange. #### Prototype Int16 NetLibGetMailExchangeByName (UInt16 libRefNum, Char *mailNameP, UInt16 maxEntries, Char hostNames[][255+1], UInt16 priorities[], Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> mailNameP | Name of the mail exchange to look up.
#####
-> maxEntries | Maximum number of host names to return.
#####
<- hostNames | Array of character strings of length 255+1. The host name results are stored in this array. This array must be able to hold at 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.
#### Result 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 #### Purpose Looks up the port number for a standard TCP/IP service, given the desired protocol. #### Prototype NetServInfoPtr NetLibGetServByName (UInt16 libRefNum, const Char *servNameP, const Char *protoNameP, NetServInfoBufPtr bufP, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> servNameP | Name of the service to look up. Possible services are "echo", "discard", "daytime", "qotd", "chargen", "ftp-data", "ftp", "telnet", "smtp", "time", "name", "finger", "pop2", "pop3", "nntp", "imap2".
#####
-> protoNameP | Desired protocol to use, either "udp" or "tcp".
#####
<- bufP | Pointer to a NetServInfoBufType struct in which to store the results of the lookup.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is 0.
#### Result 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 #### Purpose Attach a new network interface. #### Prototype Err NetLibIFAttach (UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, Int32 timeout) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> ifCreator | Creator of interface to attach.
#####
-> ifInstance | Instance number of interface to attach. The instance number is one of the values returned by NetLibIFGet.
#####
-> timeout | Timeout in ticks; -1 means infinite timeout.
#### Result 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 net library's preferences database and the interface is initialized and attached to the stack the next time the net library is opened. #### See Also NetLibIFGet, NetLibIFDetach ## NetLibIFDetach #### Purpose Detach a network interface from the protocol stack. #### Prototype Err NetLibIFDetach (UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, Int32 timeout) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> ifCreator | Creator of interface to detach.
#####
-> ifInstance | Instance number of interface to detach.
#####
-> timeout | Timeout in ticks; -1 means infinite timeout.
#### Result 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 in the net library's preferences database and the interface is not attached the next time the library is opened. #### See Also NetLibIFGet, NetLibIFAttach ## NetLibIFDown #### Purpose Bring an interface down and hang up a connection. #### Prototype Err NetLibIFDown (UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, Int32 timeout) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> ifCreator | Creator of interface to attach.
#####
-> ifInstance | Instance number of interface to attach.
#####
-> timeout | Timeout in ticks; -1 means wait forever.
#### Result 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 #### Purpose Get the creator and instance number of an installed interface by index. #### Prototype Err NetLibIFGet (UInt16 libRefNum, UInt16 index, UInt32 *ifCreatorP, UInt16 *ifInstanceP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> index | Index of the interface to get. Indices start at 0.
#####
<- ifCreatorP | The interface's creator.
#####
<- ifInstanceP | The interface's instance number.
#### Result 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 #### Purpose Retrieves a network interface specific setting. #### Prototype Err NetLibIFSettingGet (UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, UInt16 setting, void *valueP, UInt16 *valueLenP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> ifCreator | Creator of the network interface.
#####
-> ifInstance | Instance number of the network interface.
#####
-> setting | Setting to retrieve; one of the NetIFSettingEnum constants.
#####
<- valueP | Space for return value of setting.
#####
<-> valueLenP | On entry, size of valueP. On exit, actual size of setting.
#### Result 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 62.1 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 62.1 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 false, 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.
#### See Also NetLibIFSettingSet, NetLibSettingGet, NetLibSettingSet, "Interface Specific Settings" in the Palm OS Programmer's Companion, vol. II, Communications ## NetLibIFSettingSet #### Purpose Sets a network interface specific setting. #### Prototype Err NetLibIFSettingSet (UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance, UInt16 setting, void *valueP, UInt16 valueLen) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> ifCreator | Creator of the network interface.
#####
-> ifInstance | Instance number of the network interface.
#####
-> setting | The setting to set, one of the NetIFSettingEnum constants. See Table 62.1.
#####
-> valueP | Space new value of setting.
#####
-> valueLen | Size of new setting.
#### Result 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
#####
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 #### Purpose Bring an interface up and establish a connection. #### Prototype Err NetLibIFUp (UInt16 libRefNum, UInt32 ifCreator, UInt16 ifInstance) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> ifCreator | Creator of interface to attach.
#####
-> ifInstance | Instance number of interface to attach.
#### Result 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 #### Purpose Retrieves the network statistics, interface statistics, and the contents of the trace buffer. #### Prototype Err NetLibMaster (UInt16 libRefNum, UInt16 cmd, NetMasterPBPtr pbP, Int32 timeout) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> cmd | Function to perform (NetMasterEnum type). The following commands are supported:
#####
| netMasterInterfaceInfo netMasterInterfaceStats netMasterIPStats netMasterICMPStats netMasterUDPStats netMasterTCPStats netMasterTraceEventGet
#####
<-> pbP | Command parameter block.
#####
-> timeout | Timeout in ticks; -1 means wait forever.
#### Result 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 #### Purpose Opens and initializes the net library. #### Prototype Err NetLibOpen (UInt16 libRefnum, UInt16 *netIFErrsP) #### Parameters #####
-> libRefnum | Reference number of the net library.
#####
<- netIFErrsP | First error encountered when bringing up network interfaces. (See NetLibIFUp for a list of possible values.)
#### Result 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. #### See Also SysLibFind, NetLibClose, NetLibOpenCount ## NetLibOpenCount #### Purpose Retrieves the open count of the net library. #### Prototype Err NetLibOpenCount (UInt16 refNum, UInt16 *countP) #### Parameters #####
-> refNum | Reference number of the net library.
#####
<- countP | Contains the open count of the net library upon return.
#### Result #####
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 #### Purpose Receive data from a socket into a single buffer. #### Prototype Int16 NetLibReceive (UInt16 libRefNum, NetSocketRef socket, void *bufP, UInt16 bufLen, UInt16 flags, void *fromAddrP, UInt16 *fromLenP, Int32 timeout, Err *errP); #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
<- bufP | Pointer to buffer to hold received data.
#####
-> bufLen | Length of bufP buffer.
#####
-> flags | One or more netIOFlagxxx flags. See "I/O Flags."
#####
<- fromAddrP | Pointer to buffer to hold address of sender (a NetSocketAddrType).
#####
<-> fromLenP | On entry, size of fromAddrP buffer. On exit, actual size of returned address in fromAddrP.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result Returns the number of bytes successfully received. If the return value is 0, the socket has been shut down by the remote host. If the return value is -1, an error has occurred, and errP contains one of the following values: #####
0 | No error.
#####
netErrTimeout | Call timed out.
#####
netErrNotOpen | The referenced net library has not been opened yet.
#####
netErrParamErr
#####
netErrSocketNotOpen
#####
netErrWouldBlock
#####
netErrUserCancel
#### Sockets Equivalent int recvfrom (int socket, const void *bufP, int bufLen, int flags, const void *fromAddrP, int *fromLenP); int recv (int socket, const void *bufP, int bufLen, int flags); int read (int socket, const void *bufP, int bufLen); #### Comments For stream-based sockets, this call reads whatever bytes are available and returns the number of bytes actually read into the caller's buffer. If there is no data available, this call will block until at least one byte arrives, until the socket is shut down by the remote host, or until a timeout occurs. For datagram-based sockets, this call reads a complete datagram and returns the number of bytes in the datagram. If the caller's buffer is not large enough to hold the entire datagram, the end of the datagram is discarded. If a datagram is not available, this call will block until one arrives, or until the call times out. The data is read into a single buffer pointed to by bufP. #### See Also NetLibReceive, NetLibDmReceive, NetUReadN, NetLibSend, NetLibSendPB ## NetLibReceivePB #### Purpose Receive data from a socket into a multi-buffer gather-read array. #### Prototype Int16 NetLibReceivePB (UInt16 libRefNum, NetSocketRef socket, NetIOParamType *pbP, UInt16 flags, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> pbP | Pointer to parameter block containing buffer info.
#####
-> flags | One or more netIOFlagxxx flags. See "I/O Flags."
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result 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:
    typedef struct {
      UInt8        *addrP;
      UInt16       addrLen;
      NetIOVecPtr  iov;
      UInt16       iovLen;
      UInt8        *accessRights;
      UInt16       accessRightsLen;
    } NetIOParamType, *NetIOParamPtr;
You provide the following information in this struct: #####
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 #### 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. #### Prototype Int16 NetLibSelect (UInt16 libRefNum, UInt16 width, NetFDSetType *readFDs, NetFDSetType *writeFDs, NetFDSetType *exceptFDs, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> width | Number of descriptor bits to check in the readFDs, writeFDs, 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.
#### Result Returns the sum total number of ready file descriptors in *readFDs, *writeFDs, and *exceptFDs. Returns 0 upon timeout. If the return value is -1, an error has occurred, and errP contains one of the following values: #####
0 | No error
#####
netErrTimeout | Call timed out.
#####
netErrNotOpen | The referenced net library has not been opened yet.
#### Sockets Equivalent int select (int width, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); #### Comments This call blocks until one or more descriptors are ready for I/O. In the Palm OS environment, a descriptor is either a NetSocketRef or the "stdin" descriptor, sysFileDescStdIn. The sysFileDescStdIn descriptor will be ready for input whenever a user event is available like a pen tap or key press. The caller should set which bits in each descriptor set need to be checked by using the netFDZero and netFDSet macros. After this call returns, the macro netFDIsSet can be used to determine which descriptors in each set are actually ready. On exit, the total number of ready descriptors is returned and each descriptor set is updated with the appropriate bits set for each ready descriptor in that set. The following example illustrates how to use this call to check for input on a socket or a user event:
      Err     err;
      NetSocketRef    socket;
      NetFDSetType    readFDs,writeFDs,exceptFDs;
      Int16       numFDs;
      UInt16       width;

      // Create the descriptor sets
      netFDZero(&readFDs);
      netFDZero(&writeFDs);
      netFDZero(&exceptFDs);
      netFDSet(sysFileDescStdIn, &readFDs);
      netFDSet(socket, &readFDs);

      // Calculate the max descriptor number and
      // use that +1 as the max width.
      // Alternatively, we could simply use the
      // constant netFDSetSize as the width which
      // is simpler but makes the NetLibSelect call
      // slightly slower.
      width = sysFileDescStdIn;
      if (socket > width) width = socket;

      // Wait for any one of the descriptors to be
      // ready.
      numFDs = NetLibSelect(AppNetRefnum, width+1,
        &readFDs, &writeFDs, &exceptFDs,
        AppNetTimeout, &err);
Also see the NetSample example application in the Palm OS Examples folder. The function CmdTelnet in the file CmdTelnet.c shows how to use the Berkeley sockets select function and how to interpret the results. #### See Also NetLibSocketOptionSet ## NetLibSend #### Purpose Send data to a socket from a single buffer. #### Prototype Int16 NetLibSend (UInt16 libRefNum, NetSocketRef socket, void *bufP, UInt16 bufLen, UInt16 flags, void *toAddrP, UInt16 toLen, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> bufP | Pointer to data to write.
#####
-> bufLen | Length of data to write
#####
-> flags | One or more netIOFlagxxx flags. See "I/O Flags."
#####
-> toAddrP | Address to send to (a pointer to a NetSocketAddrType), or 0.
#####
-> toLen | Size of toAddrP buffer.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result Returns the number of bytes successfully sent. Returns 0 if the socket has been shut down by the remote host. If the return value is -1, an error has occurred, and errP contains one of the following values: #####
0 | No error.
#####
netErrTimeout | Call timed out.
#####
netErrNotOpen | The referenced net library has not been opened yet.
#####
netErrParamErr
#####
netErrSocketNotOpen
#####
netErrMessageTooBig
#####
netErrSocketNotConnected
#####
netErrSocketClosedByRemote
#####
netErrIPCantFragment
#####
netErrIPNoRoute
#####
netErrIPNoSrc
#####
netErrIPNoDst
#####
netErrIPktOverflow
#####
netErrOutOfCmdBlocks
#####
netErrOutOfPackets
#####
netErrInterfaceNotFound
#####
netErrInterfaceDown
#####
netErrUnreachableDest
#####
netErrNoMultiPktAddr
#####
netErrWouldBlock
#### Sockets Equivalent int sendto (int socket, const void *bufP, int bufLen, int flags, const void *toAddrP, int toLen); int send (int socket, const void *bufP, int bufLen, int flags); int write (int socket, const void *bufP, int bufLen,); #### Comments This call attempts to write data to the specified socket and returns the number of bytes actually sent, which may be less than or equal to the requested number of bytes. The data is passed in a single buffer that bufP points to. For datagram sockets, you must only send a single packet at a time. If the data is too large to fit in a single UDP packet (1536 bytes), no data is sent and -1 is returned. The toAddrP field applies only to datagram sockets without an existing connection. An error is returned if the datagram socket was previously connected and toAddrP is specified. Stream-based sockets, by definition, must have a connection established with a remote host before data can be written. Raw sockets (supported in Palm OS version 3.0 and higher) must construct the entire IP header, including the destination address, before data can be sent; thus, the address is taken from the data to be sent. If there isn't enough buffer space to send any data, this call will block until there is enough buffer space, or until a timeout. NOTE: For stream-based sockets, this call may write only a portion of the desired data. It always returns the number of bytes actually written. Consequently, the caller should be prepared to call this routine repeatedly until the desired number of bytes have been written, or until it returns 0 or -1. #### See Also NetLibSendPB, NetUWriteN, NetLibReceive, NetLibReceivePB, NetLibDmReceive ## NetLibSendPB #### Purpose Send data to a socket from a scatter-write array. #### Prototype Int16 NetLibSendPB (UInt16 libRefNum, NetSocketRef socket, NetIOParamType *pbP, UInt16 flags, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> pbP | Pointer to parameter block containing buffer info. See the description in NetLibReceivePB.
#####
-> flags | One or more netIOFlagxxx flags. See "I/O Flags."
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result 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 #### Purpose Retrieves a general setting. #### Prototype Err NetLibSettingGet (UInt16 libRefNum, UInt16 setting, void *valueP, UInt16 *valueLenP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> setting | Setting to retrieve, one of the NetSettingEnum constants.
#####
<- valueP | Space for return value of setting.
#####
<-> valueLenP | On entry, size of valueP. On exit, actual size of setting.
#### Result 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 62.2 lists the general settings and the type of each setting. #####
Table 62.2 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 #### Purpose Sets a general setting. #### Prototype Err NetLibSettingSet (UInt16 libRefNum, UInt16 setting, void *valueP, UInt16 valueLen) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> setting | Setting to set; one of the NetSettingEnum constants. See Table 62.2.
#####
-> valueP | New value for the setting.
#####
-> valueLen | Size of new setting.
#### Result Returns one of the following values: #####
0 | Success.
#####
netErrUnknownSetting | Invalid setting constant.
#####
netErrInvalidSettingSize | valueLen was invalid for the given setting.
#####
netErrBufTooSmall | valueP was too small to hold entire setting. Setting value was truncated to fit in valueP.
#####
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. 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 #### Purpose Accept a connection from a stream-based socket. #### Prototype Int16 NetLibSocketAccept (UInt16 libRefnum, NetSocketRef socket, NetSocketAddrType *sockAddrP, Int16 *addrLenP, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
<- sockAddrP | Address of remote host is returned here.
#####
<->addrLenP | On entry, length of sockAddrP buffer in bytes. On exit, length of returned address stored in *sockAddrP.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result Returns the NetSocketRef of the new socket. If the return value is -1, an error has occurred, and errP contains one of the following values: #####
0 | No error.
#####
netErrTimeout | Call timed out.
#####
netErrNotOpen | The referenced net library has not been opened yet.
#####
netErrParamErr
#####
netErrSocketNotOpen
#####
netErrSocketNotConnected
#####
netErrSocketClosedByRemote
#####
netErrWrongSocketType
#####
netErrSocketNotListening
#####
netErrUnimplemented
#### Sockets Equivalent int accept (int socket, void *sockAddrP, int *addrLenP); #### Comments Accepts the next connection request from a remote client. This call is only applicable to stream-based sockets. Before calling NetLibSocketAccept on a socket, a server application needs to: Open the socket (NetLibSocketOpen). Bind the socket to a local address (NetLibSocketBind). Set the maximum pending connection-request queue length (NetLibSocketListen). NetLibSocketAccept will block until a successful connection request is obtained from a remote client. After a successful connection is made, this call returns with the address of the remote host in *sockAddrP and the socket descriptor of a new socket as the return value. You then use the new socket to send and receive data. #### See Also NetLibSocketBind, NetLibSocketListen ## NetLibSocketAddr #### Purpose Returns the local and remote addresses currently associated with a socket. #### Prototype Int16 NetLibSocketAddr (UInt16 libRefnum, NetSocketRef socketRef, NetSocketAddrType *locAddrP, Int16 *locAddrLenP, NetSocketAddrType *remAddrP, Int16 *remAddrLenP, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socketRef | Descriptor for the open socket.
#####
<- locAddrP | Local address of socket is returned here.
#####
<->locAddrLenP | On entry, length of locAddrP buffer in bytes. On exit, length of returned address stored in *locAddrP.
#####
<- remAddrP | Address of remote host is returned here.
#####
<->remAddrLenP | On entry, length of remAddrP buffer in bytes. On exit, length of returned address stored in *remAddrP.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result 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 #### Purpose Assign a local address to a socket. #### Prototype Int16 NetLibSocketBind (UInt16 libRefnum, NetSocketRef socket, NetSocketAddrType *sockAddrP, Int16 addrLen, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> sockAddrP | Pointer to the address to give to the socket. This can be a NetSocketAddrINType or 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.
#### Result Returns 0 upon success and -1 if an error occurred. If an error occurred, errP contains one of the following values: #####
0 | No error.
#####
netErrTimeout | Call timed out.
#####
netErrNotOpen | The referenced net library has not been opened yet.
#####
netErrParamErr
#####
netErrSocketNotOpen
#####
netErrSocketAlreadyConnected
#####
netErrSocketClosedByRemote
#####
netErrOutOfCmdBlocks
#### Sockets Equivalent int bind (int socket, const void *sockAddrP, int addrLen); #### Comments Applications that want to wait for an incoming connection request from a remote host must call this function. After calling NetLibSocketBind, applications can call NetLibSocketListen and then NetLibSocketAccept to make the socket ready to accept connection requests. #### Compatibility Raw sockets are only supported in Palm OS version 3.0 and higher. See NetLibSocketOpen for instructions on how to bind raw sockets. #### See Also NetLibSocketConnect, NetLibSocketListen, NetLibSocketAccept ## NetLibSocketClose #### Purpose Close a socket. #### Prototype Int16 NetLibSocketClose (UInt16 libRefnum, NetSocketRef socket, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result 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 #### Purpose Assign a destination address to a socket and initiate three-way handshake if it's stream based. #### Prototype Int16 NetLibSocketConnect (UInt16 libRefnum, NetSocketRef socket, NetSocketAddrType *sockAddrP, Int16 addrLen, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> sockAddrP | Pointer to address to connect to.
#####
-> addrLen | Length of address in *sockAddrP.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result Returns 0 upon success and -1 if an error occurred. If an error occurred, errP contains one of the following values: #####
0 | No error.
#####
netErrTimeout | Call timed out.
#####
netErrNotOpen | The referenced net library has not been opened yet.
#####
netErrParamErr
#####
netErrSocketNotOpen
#####
netErrSocketBusy
#####
netErrNoInterfaces | Incorrect setup.
#####
netErrPortInUse
#####
netErrQuietTimeNotElapsed
#####
netErrInternal
#####
netErrSocketAlreadyConnected
#####
netErrSocketClosedByRemote
#####
netErrTooManyTCPConnections
#####
netErrWouldBlock
#####
netErrWrongSocketType
#####
netErrOutOfCmdBlocks
#### Sockets Equivalent int connect (int socket, const void *sockAddrP, int addrLen); #### See Also NetLibSocketBind, NetUTCPOpen ## NetLibSocketListen #### Purpose Put a stream-based socket into passive listen mode. #### Prototype Int16 NetLibSocketListen (UInt16 libRefnum, NetSocketRef socket, UInt16 queueLen, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> queueLen | Maximum number of pending connections allowed.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result 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 #### Purpose Open a new socket. #### Prototype NetSocketRef NetLibSocketOpen (UInt16 libRefnum, NetSocketAddrEnum domain, NetSocketTypeEnum type, Int16 protocol, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> domain | Address domain. See NetSocketAddrEnum.
#####
-> type | Desired type of connection. See NetSocketTypeEnum.
#####
-> protocol | Protocol to use. This parameter is currently ignored.
#####
| For raw sockets in the netSocketAddrINET domain, specify one of the following:
#####
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.
#### Result 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 #### Purpose Retrieves the current value of a socket option. #### Prototype Int16 NetLibSocketOptionGet (UInt16 libRefnum, NetSocketRef socket, UInt16 level, UInt16 option, void *optValueP, UInt16 *optValueLenP, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> level | Level of the option, one of the NetSocketOptLevelEnum constants. 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.
#### Result 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 #### Purpose Set a socket option. #### Prototype Int16 NetLibSocketOptionSet (UInt16 libRefnum, NetSocketRef socket, UInt16 level, UInt16 option, void *optValueP, UInt16 optValueLen, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> level | Level of the option, one of the NetSocketOptLevelEnum constants. See the comments section.
#####
-> option | One of the NetSocketOptEnum constants. See the comments section.
#####
-> optValueP | Pointer to the variable holding the new value of the option.
#####
-> optValueLen | Size of variable pointed to by optValueP.
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result Returns 0 upon success and -1 if an error occurred. If an error occurred, errP contains one of the following values: #####
0 | No error.
#####
netErrTimeout | Call timed out.
#####
netErrNotOpen | The referenced net library has not been opened yet.
#####
netErrParamErr
#####
netErrSocketNotOpen
#####
netErrUnimplemented
#####
netErrWrongSocketType
#####
netErrInvalidSettingSize
#### Sockets Equivalent int setsockopt (int socketRef, int level, int option, const void *optValueP, int optValueLen); #### Comments Sets various options associated with a socket. The caller passes a pointer to the new option value in optValueP and the size of the option in optValueLen. Table 62.3 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 62.3 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
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 #### Purpose Shut down a socket in one or both directions. #### Prototype Int16 NetLibSocketShutdown (UInt16 libRefnum, NetSocketRef socket, Int16 direction, Int32 timeout, Err *errP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> socket | Descriptor for the open socket.
#####
-> direction | Direction to shut down. One of the NetSocketDirEnum constants. Specifically:
#####
| netSocketDirInput netSocketDirOutput netSocketDirBoth
#####
-> timeout | Maximum timeout in system ticks; -1 means wait forever.
#####
<- errP | Contains an error code if the return value is -1.
#### Result 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 #### Purpose Store debugging information in the net library's trace buffer. #### Prototype Err NetLibTracePrintF (UInt16 libRefNum, const Char *formatStr, ...) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> formatStr | A printf style format string.
#####
-> ... | Arguments to the format string.
#### Result 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 #### Purpose Store debugging information in the net library's trace buffer. #### Prototype Err NetLibTracePutS (UInt16 libRefNum, Char *strP) #### Parameters #####
-> libRefNum | Reference number of the net library.
#####
-> strP | String to store in the trace buffer.
#### Result 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 #### Purpose Macro that converts a 32-bit value from network to host byte order. #### Prototype NetNToHL (x) #### Parameters #####
-> x | 32-bit value to convert.
#### Result Returns x in host byte order. #### Errors none #### Sockets Equivalent ntohl() #### See Also NetNToHS, NetHToNL, NetHToNS ## NetNToHS #### Purpose Macro that converts a 16-bit value from network to host byte order. #### Prototype NetNToHS (x) #### Parameters #####
-> x | 16-bit value to convert.
#### Result Returns x in host byte order. #### Errors None #### Sockets Equivalent ntohs() #### See Also NetHToNL, NetNToHL, NetHToNS |