Internet Library
 

 < Home   < Developers   < Development Support   < Documentation

75 Internet Library


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part IV: Libraries

75 Internet Library

Internet Library Data Structures

INetCompressionTypeEnum

INetConfigNameType

INetContentTypeEnum

INetHTTPAttrEnum

INetSchemeEnum

INetSettingEnum

INetSockSettingEnum

INetStatusEnum

Internet Library Constants

Configuration Aliases

URL Info Constants

URL Open Constants

Internet Library Functions

INetLibCacheGetObject

INetLibCacheList

INetLibCheckAntennaState

INetLibClose

INetLibConfigAliasGet

INetLibConfigAliasSet

INetLibConfigDelete

INetLibConfigIndexFromName

INetLibConfigList

INetLibConfigMakeActive

INetLibConfigRename

INetLibConfigSaveAs

INetLibGetEvent

INetLibOpen

INetLibSettingGet

INetLibSettingSet

INetLibSockClose

INetLibSockConnect

INetLibSockHTTPAttrGet

INetLibSockHTTPAttrSet

INetLibSockHTTPReqCreate

INetLibSockHTTPReqSend

INetLibSockOpen

INetLibSockRead

INetLibSockSettingGet

INetLibSockSettingSet

INetLibSockStatus

INetLibURLCrack

INetLibURLGetInfo

INetLibURLOpen

INetLibURLsAdd

INetLibWiCmd

       

This chapter provides reference material for the Internet library API:

Internet Library Data Structures

Internet Library Constants

Internet Library Functions

The header file INetMgr.h declares the Internet library API. For more information on the Internet library, see the chapter "Network Communication" in the Palm OS Programmer's Companion, vol. II, Communications.


NOTE: The information in this chapter applies only to version 3.2 or later of the Palm OS® on Palm VII® devices. These features are implemented only if the Wireless Internet Feature Set is present.

WARNING! In future OS versions, Palm, Inc. does not intend to support or provide backward compatibility for the Internet library API documented in this chapter.

Internet Library Data Structures

INetCompressionTypeEnum

The INetCompressionTypeEnum enum indicates the type of compression used for data exchanged via a socket. One of these enumerated types is set as the value of the inetSockSettingCompressionTypeID socket setting (a read-only setting).


typedef enum { 
inetCompressionTypeNone = 0, 
inetCompressionTypeBitPacked, 
inetCompressionTypeLZ77 
} INetCompressionTypeEnum; 

Value Descriptions

inetCompressionTypeNone
No compression.
inetCompressionTypeBitPacked
Custom 5-bit compression scheme. This is typically used for data sent from the Palm Web Clipping Proxy server.
inetCompressionTypeLZ77
Not used; reserved for future use.

INetConfigNameType

The INetConfigNameType structure holds the name of an Internet library network configuration. A configuration is a set of specific values for the Internet library settings. The Internet 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 use an alias anywhere in the API you would use a configuration. System-defined configuration aliases are listed in "Configuration Aliases".

This structure is used in the functions INetLibConfigIndexFromName, INetLibConfigRename, and INetLibConfigSaveAs.


#define inetConfigNameSize 32; 
  
typedef struct { 
Char name[inetConfigNameSize]; // name of configuration 
} INetConfigNameType, *INetConfigNamePtr; 

Field Description

name
A configuration name (up to 32 characters).

INetContentTypeEnum

The INetContentTypeEnum enum specifies the type of content to be exchanged via a socket. One of these enumerated types is set as the value of the inetSockSettingContentTypeID socket setting (a read-only setting).


typedef enum { 
inetContentTypeTextPlain = 0, 
inetContentTypeTextHTML, 
inetContentTypeImageGIF, 
inetContentTypeImageJPEG, 
inetContentTypeApplicationCML, 
inetContentTypeImagePalmOS, 
inetContentTypeOther 
} INetContentTypeEnum; 

Value Descriptions

inetContentTypeTextPlain
Not used
inetContentTypeTextHTML
Not used
inetContentTypeImageGIF
Not used
inetContentTypeImageJPEG
Not used
inetContentTypeApplicationCML
Compressed HTML content (format used by the Palm Web Clipping Proxy server and PQAs)
inetContentTypeImagePalmOS
Palm OS® bitmap
inetContentTypeOther
Some undefined content type

INetHTTPAttrEnum

The INetHTTPAttrEnum enum specifies HTTP request and response attributes that are set by INetLibSockHTTPAttrSet and returned by INetLibSockHTTPAttrGet.


typedef enum { 
  
//----------------------------------------------------------- 
// Request only attributes 
//----------------------------------------------------------- 
// The following are ignored unless going through a CTP proxy 
inetHTTPAttrWhichPart, // (W) UInt32 (0 -> N) 
inetHTTPAttrIncHTTP, // (W) UInt32 (Boolean) only applicable
       // when inetHTTPAttrConvAlgorithm set to ctpConvNone 
inetHTTPAttrCheckMailHi, // (W) UInt32 
inetHTTPAttrCheckMailLo, // (W) UInt32 
inetHTTPAttrReqContentVersion, // (W) UInt32, desired content 
           // version. Represented as 2 low bytes. Lowest byte is
          // minor version, next higher byte is major version. 
//-------------------------------------------------------------- 
// Response only attributes 
//-------------------------------------------------------------- 
// Server response info 
inetHTTPAttrRspSize, // (R) UInt32, entire HTTP Response size 
           // including header and data 
inetHTTPAttrResult, // (R) UInt32 (ctpErrXXX when using CTP Proxy) 
inetHTTPAttrErrDetail, // (R) UInt32 (server/proxy err code when
           // using CTP Proxy) 
inetHTTPAttrReason, // (R) Char[] 
// Returned entity attributes 
inetHTTPAttrContentLength, // (R) UInt32 
inetHTTPAttrContentLengthUncompressed, // (R) UInt32 (in bytes) 
inetHTTPAttrContentLengthUntruncated, //(R) UInt32 
inetHTTPAttrContentVersion, // (R) UInt32, actual content version.
          // Represented as 2 low bytes. Lowest byte is minor
          // version, next higher byte is major version.  
inetHTTPAttrContentCacheID, // (R) UInt32, cacheID for this item 
inetHTTPAttrReqSize // (R) UInt32 size of request sent 
} INetHTTPAttrEnum; 

Value Descriptions

inetHTTPAttrWhichPart
An index to the part of the response data desired, if the response data is partitioned into chunks. Write-only.
inetHTTPAttrIncHTTP
A Boolean that, if set, causes HTTP header data to be included as part of the content when retrieving raw data. Applicable only when inetSettingConvAlgorithm is set to ctpConvNone. Write-only.
inetHTTPAttrCheckMailHi
High-order byte of ID for checking mail. Write-only.
inetHTTPAttrCheckMailLo
Low-order byte of ID for checking mail. Write-only.
inetHTTPAttrReqContentVersion
Desired content version. Represented as 2 low bytes. Lowest byte is minor version, next higher byte is major version. Write-only.
inetHTTPAttrRspSize
Size of entire HTTP (header and data). Read-only.
inetHTTPAttrResult
Transport protocol error code. Read-only.
inetHTTPAttrErrDetail
Server/proxy error code when using the Palm Web Clipping Proxy server. Read-only.
inetHTTPAttrReason
Transport protocol error message. Read-only.
inetHTTPAttrContentLength
Size of response data. Read-only.
inetHTTPAttrContentLengthUncompressed
Size of uncompressed response data. Read-only.
inetHTTPAttrContentLengthUntruncated
Total size of response data (it may have been truncated to less than this). Read-only.
inetHTTPAttrContentVersion
Actual content version. Represented as 2 low bytes. Lowest byte is minor version, next higher byte is major version. Read-only.
inetHTTPAttrContentCacheID
Cache ID for this item. Read-only.
inetHTTPAttrReqSize
Size of request sent. Read-only.

INetSchemeEnum

The INetSchemeEnum enum specifies a protocol (http, https, etc.) used by a socket. Specify one of these enumerated types for the INetSockSettingScheme socket setting and for the scheme parameter to the INetLibSockOpen call.


typedef enum { 
inetSchemeUnknown = -1, 
inetSchemeDefault = 0,   // not used 
  
inetSchemeHTTP, // http: 
inetSchemeHTTPS, // https: 
inetSchemeFTP, // ftp: 
inetSchemeGopher, // gopher: 
inetSchemeFile, // file: 
inetSchemeNews, // news: 
inetSchemeMailTo, // mailto: 
inetSchemePalm, // palm: 
inetSchemePalmCall, // palmcall: 
inetSchemeMail, // not applicable to URLs, but used 
                      //  for the INetLibSockOpen call when 
                      //  creating a socket for mail IO 
inetSchemeMac, // mac: - Mac file system HTML 
  
inetSchemeFirst = inetSchemeHTTP, // first one 
inetSchemeLast = inetSchemeMail // last one 
} INetSchemeEnum; 

Value Descriptions

inetSchemeHTTP
Use the HTTP protocol.
inetSchemeHTTPS
Use the HTTPS protocol (for a secure connection).
inetSchemeFTP
Use the FTP protocol. Not implemented.
inetSchemeGopher
Use the Gopher protocol. Not implemented.
inetSchemeFile
Launch local PQA file
inetSchemeNews
Use the News protocol. Not implemented.
inetSchemeMailTo
Launch the local messaging application, passing a "to" address.
inetSchemePalm
Launches a local application database. The URL is expected to be in the form cccc.tttt, where cccc is a four character creator name and tttt is a four character database type. This pair of strings is used to identify an application database to receive the launch message via a call to SysUIAppSwitch.
inetSchemePalmCall
Launches a local application database. The URL is expected to be in the form cccc.tttt, where cccc is a four character creator name and tttt is a four character database type. This pair of strings is used to identify an application database to receive the launch message via a call to SysAppLaunch.
inetSchemeMail
Creates a socket for mail I/O.
inetSchemeMac
Handles opening Mac OS file system HTML URLs. For use by the Simulator only.

INetSettingEnum

The INetSettingEnum enum specifies a setting to be returned or set by the INetLibSettingGet or INetLibSettingSet calls.


typedef enum { 
inetSettingCacheSize, // (RW) UInt32, max size of cache 
inetSettingCacheRef, // (R) DmOpenRef, ref of cache DB 
inetSettingNetLibConfig, // (RW) UInt32, NetLib config to use 
inetSettingRadioID, // (R) UInt32[2], the 64-bit radio ID 
inetSettingBaseStationID, // (R)  UInt32, the radio base station Id 
inetSettingMaxRspSize, // (W) UInt32 (in bytes) 
inetSettingConvAlgorithm, // (W) UInt32 (CTPConvEnum) 
inetSettingContentWidth, // (W) UInt32 (in pixels) 
inetSettingContentVersion, // (W) UInt32, content version (encoder 
                                      // version) 
inetSettingNoPersonalInfo, // (RW) UInt32, send no deviceID/zipcode 
inetSettingUserName, 
inetSettingLast 
} INetSettingEnum; 

Value Descriptions

inetSettingCacheSize
Maximum size of cache (in bytes).
inetSettingCacheRef
DmOpenRef, reference to cache database. Read-only.
inetSettingNetLibConfig
The index of the net library network configuration to use. This value is saved as part of the preferences for each Internet library configuration. A value of 0 means to use the current configuration.
inetSettingRadioID
64-bit radio ID. Read-only. Used for wireless connections only.
inetSettingBaseStationID
Radio base station ID. Read-only. Used for wireless connections only.
inetSettingMaxRspSize
Maximum response size, in bytes. The default is 1024 bytes. Write-only.
inetSettingConvAlgorithm
Content conversion desired. Write-only. Possible values include:
ctpConvCML (use 5-bit compression scheme),
ctpConvCML8Bit (use 5-bit compression scheme, but in 8-bit form for debugging),
ctpConvCMLLZ77 (use LZ77 compression scheme),
ctpConvNone (no conversion; data is returned in native format)
inetSettingContentWidth
Width of the display for content. The default setting is 160 (pixels). Write-only.
inetSettingContentVersion
Content version (encoder version). Write-only. This setting is used to let the server know what encoder version it should use to encode content sent to the Palm client. Normally you don't need to set this value as it is initialized by INetLibOpen. The default encoder version is 0x8001.
inetSettingNoPersonalInfo
Send no device ID or zipcode information to the proxy server. This value is saved as part of the preferences for each Internet library configuration.
inetSettingUserName
Not applicable.

INetSockSettingEnum

The INetSockSettingEnum enum specifies a socket setting to be returned or set by the INetLibSockSettingGet or INetLibSockSettingSet calls.


typedef enum { 
inetSockSettingScheme, // (R) UInt32, INetSchemeEnum 
inetSockSettingSockContext, // (RW) UInt32, 
inetSockSettingCompressionType, // (R) Char[] 
inetSockSettingCompressionTypeID, // (R) UInt32 
                                              // (INetCompressionTypeEnum) 
inetSockSettingContentType, // (R) Char[] 
inetSockSettingContentTypeID, // (R) UInt32 (INetContentTypeEnum) 
inetSockSettingData, // (R) UInt32, pointer to data 
inetSockSettingDataHandle,// (R) UInt32, handle to data 
inetSockSettingDataOffset,// (R) UInt32, offset to data from handle 
inetSockSettingTitle, // (W) Char[] 
inetSockSettingURL, // (R) Char[] 
inetSockSettingIndexURL, // (RW) Char[] 
inetSockSettingFlags, // (RW) UInt16, one or more of
                              // inetOpenURLFlagXXX flags 
inetSockSettingReadTimeout, // (RW) UInt32, read timeout in ticks 
inetSockSettingContentVersion,// (R) UInt32, content version number 
inetSockSettingLast 
} INetSockSettingEnum; 

Value Descriptions

inetSockSettingScheme
Requested scheme; one of the INetSchemeEnum values. Read-only.
inetSockSettingSockContext
Not used.
inetSockSettingCompressionType
Name of requested compression type. Read-only.
inetSockSettingCompressionTypeID
Requested compression type; one of the INetCompressionTypeEnum values. Read-only.
inetSockSettingContentType
String containing the MIME type of the content. Used only on received raw data. Read-only.
inetSockSettingContentTypeID
Content type of socket data; one of the INetContentTypeEnum values. Read-only.
inetSockSettingData
Pointer to socket data. Read-only.
inetSockSettingDataHandle
Handle to socket data. Read-only.
inetSockSettingDataOffset
Offset to socket data from handle. Read-only.
inetSockSettingTitle
Web page title. This value is written to the cache (and the Web Clipping Application Viewer uses it later in a history list of cache entries). Write-only.
inetSockSettingURL
URL of requested data. Read-only.
inetSockSettingIndexURL
Index (or master) URL of requested data (for cache indexing). This is the topmost web page in a group of hierarchical pages; it serves to group the pages together and to filter cache list results. The Web Clipping Application Viewer sets this to the URL of the active PQA, for all pages linked from the PQA.
inetSockSettingFlags
URL request flags; one or more of inetOpenURLFlag... flags (see URL Open Constants).
inetSockSettingReadTimeout
The default timeout value for reads when the application uses the event mechanism. The time since last receiving data from a socket is monitored and a timeout error status event is returned from INetLibGetEvent if the timeout is exceeded.
inetSockSettingContentVersion
Content version number. Read-only.

INetStatusEnum

The INetStatusEnum enum specifies the status of the socket. The status is returned in the inetSockStatusChangeEvent event structure and by the call INetLibSockStatus.


typedef enum { 
inetStatusNew, // just opened 
inetStatusResolvingName, // looking up host address 
inetStatusNameResolved, // found host address 
inetStatusConnecting, // connecting to host 
inetStatusConnected, // connected to host 
inetStatusSendingRequest, // sending request 
inetStatusWaitingForResponse, // waiting for response 
inetStatusReceivingResponse, // receiving response 
inetStatusResponseReceived, // response received 
inetStatusClosingConnection, // closing connection 
inetStatusClosed, // closed 
inetStatusAcquiringNetwork, // network temporarily
                                    // unreachable; socket on hold 
inetStatusPrvInvalid = 30 // internal value, not returned by 
                                    // INetMgr. Should be last. 
} INetStatusEnum; 

Value Descriptions

inetStatusNew
Just opened
inetStatusResolvingName
Looking up host address
inetStatusNameResolved
Found host address
inetStatusConnecting
Connecting to host
inetStatusConnected
Connected to host
inetStatusSendingRequest
Sending request
inetStatusWaitingForResponse
Waiting for response
inetStatusReceivingResponse
Receiving response
inetStatusResponseReceived
Response received
inetStatusClosingConnection
Closing connection
inetStatusClosed
Connection closed
inetStatusAcquiringNetwork
Network temporarily unreachable; socket on hold
inetStatusPrvInvalid
Not used

Internet Library Constants

Configuration Aliases

The constants listed here specify Internet library network configuration alias names. Most of the Internet library API requires a configuration index rather than a name. Use INetLibConfigIndexFromName to obtain the alias's index from the name. For more information, see INetConfigNameType.

The following aliases are defined for configuration names:

Alias
Name string
Description
inetCfgNameDefault
".Default"
Initially points to a generic configuration with no proxy. This uses the configuration set by the user in the Network preferences panel.
inetCfgNameDefWireline
".DefWireline"
Initially points to a generic configuration with no proxy. This uses the configuration set by the user in the Network preferences panel.
inetCfgNameDefWireless
".DefWireless"
Initially points to a generic configuration with no proxy. This uses the configuration set by the user in the Network preferences panel.
inetCfgNameCTPDefault
".CTPDefault"
Initially points to either ".CTPWireless" (on Palm VII® units) or ".CTPWireline" (on all other units). On the Palm VII unit, the Web Clipping Application Viewer application uses this configuration.
inetCfgNameCTPWireline
".CTPWireline"
Initially points to a wireline configuration that uses the Palm Web Clipping Proxy server.
inetCfgNameCTPWireless
".CTPWireless"
Initially points to a wireless configuration that uses the Palm.NetTM wireless system and the Palm Web Clipping Proxy server.

URL Info Constants

The inetURLInfoFlag... constants convey information about a URL and are returned by the function INetLibURLGetInfo.

Constant
Value
Description
inetURLInfoFlagIsSecure
0x0001
URL was encrypted.
inetURLInfoFlagIsRemote
0x0002
URL was retrieved from the net.
inetURLInfoFlagIsInCache
0x0004
URL is stored in the cache.

URL Open Constants

The inetOpenURLFlag... constants control how the INetLibURLOpen call operates with respect to caching and encryption. These flags are also used for the inetSockSettingFlags socket setting.

Constant
Value
Description
inetOpenURLFlagLookInCache
0x0001
Read data from the cache, if available.
inetOpenURLFlagKeepInCache
0x0002
Store the item in the cache, overwriting any other entries with an equivalent URL.
inetOpenURLFlagForceEncOn
0x0008
Use encryption even if scheme does not desire it.
inetOpenURLFlagForceEncOff
0x0010
Do not use encryption even if scheme desires it.

Internet Library Functions

INetLibCacheGetObject

Purpose

Returns information about an entry in the cache database, including a handle to the record. Either the URL or the unique ID can be used to find the cache entry.

Prototype

Err INetLibCacheGetObject (UInt16 libRefnum, MemHandle clientParamH, UInt8 *urlTextP, UInt32 uniqueID, INetCacheInfoPtr cacheInfoP)

Parameters

-> libRefnumRefnum of the Internet library.
-> clientParamHInet handle allocated by INetLibOpen.
-> urlTextPPointer to URL text string to find. If this parameter is NULL, then uniqueID is used to find the entry.
-> uniqueIDUnique ID of the cache entry to find. This value can be obtained by calling INetLibCacheList. This parameter is ignored if urlTextP is specified.
<- INetCacheInfoPtrPointer to a structure where information about the cache entry is returned. See the Comments section for details.

Result

0
No error
inetErrParamsInvalid
One or more of the parameters are invalid.

Comments

The INetCacheInfoPtr type returned from this function is defined as a pointer to an INetCacheInfoType structure, which has the following definition:

typedef struct { 
MemHandle recordH; // handle to the cache record 
INetContentTypeEnum contentType; 
INetCompressionTypeEnum encodingType; 
UInt32 uncompressedDataSize; 
UInt8 flags; // unused 
UInt8 reserved; 
UInt16 dataOffset; // offset to content 
UInt16 dataLength; // size of content 
UInt16 urlOffset; // offset to URL 
UInt32 viewTime; // time last viewed 
UInt32 createTime; // time entry was created 
UInt16 murlOffset; // offset to master URL 
} INetCacheInfoType, *INetCacheInfoPtr; 

Compatibility

Implemented only if Wireless Internet Feature Set is present.

INetLibCacheList

Purpose

Returns an item from the cache list, based on its URL and index in the list.

Prototype

Err INetLibCacheList (UInt16 libRefnum, MemHandle inetH, UInt8 *cacheIndexURLP, UInt16 *indexP, UInt32 *uidP, INetCacheEntryP cacheP)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen.
-> cacheIndexURLPPointer to a master URL string. Cache entries indexed with this master URL are returned. The Web Clipping Application Viewer sets the master URL of a cache page to the URL of the active PQA, so all pages linked from the PQA have the same master URL.
<-> indexPPointer to the index of the entry. Specify an index to find entries at this index or higher in the list. Specify NULL to search from the beginning, the first time you call this function. The index of the entry following the one found is returned on exit.
<- uidPPointer to a long value where the unique ID of the found cache entry is returned.
<- cachePPointer to a structure where information about the found cache entry is returned. See the Comments section for details.

Result

0
No error
inetErrTypeNotCached
Cache entry under requested index not found
inetErrParamsInvalid
The cacheIndexURLP parameter is NULL
inetErrCacheInvalid
The cache database doesn't exist

Comments

This function first sorts the list of cache entries by URL. Then it returns in uidP the unique ID of the first cache entry with an index equal to or greater than indexP. The indexP value is updated to point to the next entry upon return.

To generate a complete list of cache entries having the same master URL (as for a history list), call this function repeatedly, always specifying the updated index, until it returns the error inetErrTypeNotCached.

Note that a URL can exist multiple times in the Web Clipping Application Viewer cache database, thus the need for the uidP value.

The INetCacheEntryP type returned from this function is defined as a pointer to an INetCacheEntryType structure, which has the following definition:

typedef struct { 
UInt8 *urlP; // ptr to URL string 
UInt16 urlLen; // length of URL string 
UInt8 *titleP; // ptr to title string 
UInt16 titleLen; // length of title string 
UInt32 lastViewed; // time last viewed 
                   // seconds since 1/1/1904 
UInt32 firstViewed; // time first viewed 
                   // seconds since 1/1/1904 
} INetCacheEntryType, *INetCacheEntryP; 

Compatibility

Implemented only if Wireless Internet Feature Set is present.

INetLibCheckAntennaState

Purpose

Checks the antenna state and displays a dialog asking the user to raise it if it is down.

Prototype

Err INetLibCheckAntennaState(UInt16 refNum)

Parameters

-> refNumRefnum of the Internet library.

Result

0
The user raised the antenna.
netErrUserCancel
The user closed the dialog by tapping Cancel.

This call can also return data manager errors if it fails internally.

Comments

Applications don't need to check the antenna state by using this call. If an application opens the Internet library, the Internet library checks the antenna state when needed and displays the dialog to prompt the user to raise the antenna.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

INetLibClose

Purpose

Closes up and frees an inet handle. Closes or decrements the open count of the net library.

Prototype

Err INetLibClose (UInt16 libRefnum, MemHandle inetH)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen.

Result

0
No error

Comments

This call must be made by an application when it's done with the Internet library. It closes any Internet sockets open by the application, disposes the memory referenced by the given inet handle, and calls NetLibClose, if necessary, to close the net Library or decrement its open count.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibOpen

INetLibConfigAliasGet

Purpose

Determines to which configuration a built-in alias points.

Prototype

Err INetLibConfigAliasGet (UInt16 refNum, UInt16 aliasIndex, UInt16 *indexP, Boolean *isAnotherAliasP)

Parameters

-> libRefnumRefnum of the Internet library.
-> aliasIndexIndex of alias configuration to query. This is the index of the configuration in the internal array of configurations stored by the system. This is the same as the index of the item in the array returned by INetLibConfigList, or the index returned by INetLibConfigIndexFromName.
<- indexPPointer where the index of the configuration pointed to by aliasIndex is returned. 0 is returned if aliasIndex does not point to another configuration.
<- isAnotherAliasPIf *indexP is the index of another alias configuration, this Boolean is set to true.

Result

0
No error
inetErrParamsInvalid
aliasIndex is not valid
inetErrConfigNotAlias
aliasIndex is not an alias configuration

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibConfigAliasSet

INetLibConfigAliasSet

Purpose

Points any of the built-in aliases (".DefWireline", ".DefWireless", etc.) to a given defined configuration.

Prototype

Err INetLibConfigAliasSet (UInt16 refNum, UInt16 configIndex, UInt16 aliasToIndex)

Parameters

-> libRefnumRefnum of the Internet library.
-> configIndexIndex of configuration to set. This is the index of the configuration in the internal array of configurations stored by the system. This is the same as the index of the item in the array returned by INetLibConfigList, or the index returned by INetLibConfigIndexFromName.
-> aliasToIndexIndex of configuration that the alias identified by configIndex is to point to. Specify 0 to remove an existing alias assignment.

Result

0
No error
inetErrConfigNotAlias
configIndex is not an alias configuration
inetErrParamsInvalid
configIndex or aliasToIndex is not valid
inetErrConfigCantPointToAlias
Alias doesn't point to a real entry

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibConfigAliasGet

INetLibConfigDelete

Purpose

Deletes a configuration.

Prototype

Err INetLibConfigDelete (UInt16 refNum, UInt16 index)

Parameters

-> refnumRefnum of the Internet library.
-> indexIndex of configuration to delete. This is the index of the configuration in the internal array of configurations stored by the system. This is the same as the index of the item in the array returned by INetLibConfigList, or the index returned by INetLibConfigIndexFromName.

Result

0
No error
inetErrParamsInvalid
Index not valid
inetErrConfigCantDelete
Attempted to delete an alias configuration

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibConfigIndexFromName, INetLibConfigList

INetLibConfigIndexFromName

Purpose

Returns the index of a configuration given it's name.

Prototype

Err INetLibConfigIndexFromName (UInt16 refNum, INetConfigNamePtr nameP, UInt16 *indexP)

Parameters

-> refnumRefnum of the Internet library.
-> namePPointer to an INetConfigNameType structure that names the configuration whose index you want to get.
<- indexPPointer where the index of the configuration identified in nameP is returned.

Result

0
No error
inetErrConfigNotFound
Could not find requested configuration name

Comments

If you name an alias, this routine returns the index of the alias entry, not the configuration the alias points to. This way the alias can be pointed to a different configuration.

Applications should store the index of the configuration they're using, rather than the name, so that they won't be confused if the user edits the name of the configuration from the Preferences panel.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibConfigList

INetLibConfigList

Purpose

Returns an array containing a list of the available Internet library network configurations.

Prototype

Err INetLibConfigList (UInt16 refNum, INetConfigNameType nameArray[], UInt16 *arrayEntriesP)

Parameters

-> refnumRefnum of the Internet library.
-> nameArrayPointer to an array of INetConfigNameType structs that is to be filled in by this routine.
<-> arrayEntriesPOn entry, a pointer to the number of entries available in nameArray; on exit, a pointer to the total number of entries in the system (which could exceed the size of the array you pass in).

Result

0
No error

Comments

This routine can be used to obtain a list of available configurations for selection by the user.

Note that the built-in alias configurations, which start with a period, should not be displayed to the user as selectable choices. They are designed for internal use by applications that need a predetermined type of service (like ".CTPWireless" for PQA applications.) Also, any configurations that start with an underscore, like "_CTPRAM", should not be displayed. These typically are configurations created by the Internet library for internal use and cannot be edited using the Network preferences panel.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibConfigMakeActive

INetLibConfigMakeActive

Purpose

Makes the given configuration active without having to close and reopen the Internet library by using INetLibOpen.

Prototype

Err INetLibConfigMakeActive (UInt16 refNum, MemHandle inetH, UInt16 configIndex)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen.
-> configIndexIndex of configuration to activate. This is the index of the configuration in the internal array of configurations stored by the system. This is the same as the index of the item in the array returned by INetLibConfigList, or the index returned by INetLibConfigIndexFromName.

Result

0
No error

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibConfigSaveAs, INetLibConfigList, INetLibConfigIndexFromName

INetLibConfigRename

Purpose

Renames a configuration.

Prototype

Err INetLibConfigRename (UInt16 refNum, UInt16 index, INetConfigNamePtr newNameP)

Parameters

-> libRefnumRefnum of the Internet library.
-> indexIndex of configuration to rename. This is the index of the configuration in the internal array of configurations stored by the system. This is the same as the index of the item in the array returned by INetLibConfigList, or the index returned by INetLibConfigIndexFromName.
-> newNamePPointer to an INetConfigNameType structure holding the new name of the configuration. The name cannot start with a period or an underscore.

Result

0
No error
inetErrConfigBadName
Trying to save as an alias (beginning with ".") or as a built-in configuration (beginning with "_").
inetErrParamsInvalid
Invalid index
inetErrConfigCantDelete
Configuration to be renamed is either an alias or a built-in configuration

Comments

After renaming, the configuration index stays the same so that applications that are set up to use that configuration will still work correctly. Note that built-in configuration aliases (ones that start with a period) cannot be renamed.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

INetLibConfigSaveAs

Purpose

Saves the current network configuration settings under the given name.

Prototype

Err INetLibConfigSaveAs (UInt16 refNum, MemHandle inetH, INetConfigNamePtr nameP)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen.
-> namePPointer to an INetConfigNameType structure holding the name of the configuration. The name cannot start with a period or an underscore.

Result

0
No error
inetErrConfigBadName
Trying to save as an alias (beginning with ".") or as a built-in configuration (beginning with "_").
inetErrConfigTooMany
The internal configurations table is full. No more entries can be stored.

Comments

If the configuration name specified already exists, it is replaced with the new settings.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

INetLibGetEvent

Purpose

A replacement for EvtGetEvent that informs an application of status changes to Internet sockets as well as user interface events.

Prototype

void INetLibGetEvent (UInt16  libRefnum, MemHandle inetH, INetEventType *eventP, Int32 timeout)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen, or NULL.
<-> eventPThe event structure is returned via this pointer.
-> timeoutTimeout in ticks. Specify evtWaitForever to wait forever.

Result

0
No error

Comments

This call is designed to replace EvtGetEvent in applications which use the Internet library. For convenience, if inetH is NULL, INetLibGetEvent is equivalent to EvtGetEvent.

INetLibGetEvent returns two additional events besides those returned by EvtGetEvent: inetSockReadyEvent and inetSockStatusChangeEvent.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSockStatus, INetLibURLOpen, INetLibSockOpen, INetLibSockRead

INetLibOpen

Purpose

Creates a new application inet handle structure. Opens or increments the open count of the net library.

Prototype

Err INetLibOpen (UInt16 libRefnum, UInt16 config, UInt32 flags, DmOpenRef cacheRef, UInt32 cacheSize, MemHandle *inetHP)

Parameters

-> libRefnumRefnum of the Internet library. Pass the value "INet.lib" to SysLibFind to return this refnum.
-> configIndicates the type of network service desired by the application. Returned by INetLibConfigIndexFromName.
-> flagsCurrently unused; set to 0.
-> cacheRefDocument cache database reference. Obtain this by using one of the DmOpenDatabase... calls. Pass NULL if you don't want to use a cache.
-> cacheSizeMaximum size of the document cache (in bytes). This is ignored if you pass NULL for cacheRef.
<- inetHPPointer to a handle variable.

Result

0
No error
inetErrTooManyClients
Too many clients opened already
inetErrIncompatibleInterface
The net library is already open with an incompatible interface

Comments

This call must be made by an application before it can use any other Internet library calls. This call opens the Internet library and returns a pointer to an inet handle, which is then passed to subsequent calls to the Internet library. Every application that opens the Internet library gets its own unique inet handle.

When an application is done using the Internet library, it must call INetLibClose, which closes both the Internet library and the net library, if necessary.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibClose, INetLibConfigIndexFromName

INetLibSettingGet

Purpose

Retrieves current settings for an inet handle.

Prototype

Err INetLibSettingGet (UInt16 libRefnum, MemHandle inetH, UInt16 setting, void *bufP, UInt16 *bufLenP)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen.
-> settingThe setting to get. Specify one of the INetSettingEnum enumerated types.
<- bufPPointer to buffer where the return value is to be put.
<-> bufLenPSize of bufP on entry. Size of setting value on exit.

Result

0
No error
inetErrParamsInvalid
Invalid setting requested
inetErrSettingSizeInvalid
*bufLenP is the incorrect size for the requested setting

Comments

This call can be used to retrieve the current settings of an inet handle. Some settings have default values that are stored in the system preferences database; see INetSettingEnum for details.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibOpen, INetLibSettingSet, INetSettingEnum

INetLibSettingSet

Purpose

Changes a setting for an inet handle.

Prototype

Err INetLibSettingSet (UInt16 libRefnum, MemHandle inetH, UInt16 setting, void *bufP, UInt16 bufLen)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen.
-> settingThe setting to set. Specify one of the INetSettingEnum enumerated types.
-> bufPPointer to the new setting value.
-> bufLenSize of the value in bufP.

Result

0
No error
inetErrParamsInvalid
Invalid setting specified
inetErrSettingSizeInvalid
bufLen is the incorrect size for the specified setting

Comments

Any changes made to the settings last only as long as the inetH is around (until INetLibClose is called) and do not affect other applications that might be using the Internet library.

An important note is that settings made through this call essentially change the default values for any sockets subsequently created through INetLibURLOpen or INetLibSockOpen.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSettingGet, INetSettingEnum

INetLibSockClose

Purpose

Closes an inet socket handle.

Prototype

Err INetLibSockClose (UInt16 libRefnum, MemHandle socketH)

Parameters

-> libRefnumRefnum of the Internet library.
-> socketHHandle of the socket to close.

Result

0
No error

Comments

This call closes down and releases all memory associated with a socket created by INetLibSockOpen or INetLibURLOpen.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibOpen, INetLibSockOpen, INetLibURLOpen

INetLibSockConnect

Purpose

Establishes a connection with a remote host.

Prototype

Err INetLibSockConnect (UInt16 libRefnum, MemHandle sockH, UInt8 *hostnameP, UInt16 port, Int32 timeou)

Parameters

-> libRefnumRefnum of the Internet library.
-> sockHHandle (allocated by INetLibSockOpen or INetLibURLOpen) of the socket to connect.
-> hostnamePPointer to host name string; can be dotted decimal text string.
-> portPort number, or 0 for default port.
-> timeouTimeout in ticks. Specify evtWaitForever to wait forever.

Result

0
No error

Comments

This call associates a remote host name and port number with a socket and, depending on the socket protocol, initiates a connection with that remote host.

This call may return immediately before actually finishing the connect. The application can simply go ahead and submit additional calls such as INetLibSockRead, or it may wait for the connect to complete by either polling INetLibSockStatus until the socket status is inetStatusConnected (not recommended), or by waiting for an inetSockStatusChangeEvent event from INetLibGetEvent and checking the status then (preferred).

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSockOpen, INetLibSockStatus, INetLibGetEvent

INetLibSockHTTPAttrGet

Purpose

Queries HTTP request header formed by the local host, or the response header information returned by a remote host.

Prototype

Err INetLibSockHTTPAttrGet (UInt16 libRefnum, MemHandle sockH, UInt16 attr, UInt16 attrIndex, void *bufP, UInt32 *bufLenP)

Parameters

-> libRefnumRefnum of the Internet library.
-> sockHHandle (allocated by INetLibSockOpen or INetLibURLOpen) of the socket.
-> attrThe attribute to get. Specify one of the INetHTTPAttrEnum values.
-> attrIndexThe attribute index (if any). Currently unused.
<- bufPPointer to the address where the result is returned.
<-> bufLenPPointer to the size of bufP on entry; size of returned value on exit.

Result

0
No error
inetErrSettingNotImplemented
Invalid setting specified
inetErrSettingSizeInvalid
bufLen is the incorrect size for the specified setting

Comments

This call queries either the request header formed by INetLibSockHTTPReqCreate and INetLibSockHTTPAttrSet, or the response header returned by the remote host.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSockHTTPReqCreate

INetLibSockHTTPAttrSet

Purpose

Adds additional HTTP request headers to an HTTP request in a socket.

Prototype

Err INetLibSockHTTPAttrSet (UInt16 libRefnum, MemHandle sockH, UInt16 attr, UInt16 attrIndex, UInt8 *bufP, UInt16 bufLen, UInt16 flags)

Parameters

-> libRefnumRefnum of the Internet library.
-> sockHHandle (allocated by INetLibSockOpen or INetLibURLOpen) of the socket.
-> attrThe attribute to set. Specify one of the INetHTTPAttrEnum values.
-> attrIndexThe attribute index (if any). Currently unused.
-> bufPPointer to additional header text to add.
-> bufLenLength of bufP.
-> flagsFlags that control the addition of new headers. Currently unused.

Result

0
No error
inetErrSettingNotImplemented
Invalid setting specified
inetErrSettingSizeInvalid
bufLen is the incorrect size for the specified setting

Comments

This call modifies attributes of an HTTP request formed by INetLibSockHTTPReqCreate. Generally, attributes are set only before calling INetLibSockHTTPReqSend.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSockHTTPReqCreate, INetLibSockHTTPReqSend

INetLibSockHTTPReqCreate

Purpose

Forms an HTTP request for the socket.

Prototype

Err INetLibSockHTTPReqCreate (UInt16 libRefnum, MemHandle sockH, UInt8 *verbP, UInt8 *resNameP, UInt8 *refererP)

Parameters

-> libRefnumRefnum of the Internet library.
-> sockHHandle (allocated by INetLibSockOpen or INetLibURLOpen) of the socket.
-> verbPReserved for future use.
-> resNamePPointer to a string holding the name of the resource to get or put.
-> refererPPointer to a string holding the name of the referring URL, or NULL if none.

Result

0
No error
inetErrParamsInvalid
Not an HTTP socket

Comments

This call forms an HTTP request for the socket. The request is not actually sent to the remote host until INetLibSockHTTPReqSend is called. The HTTP verb used in the request is determined by the value of the writeP parameter passed to INetLibSockHTTPReqSend: if this parameter is NULL, "GET" is used. Otherwise, "POST" is used.

After a call to INetLibSockHTTPReqCreate but before a call to INetLibSockHTTPReqSend, the application can add additional HTTP request headers using INetLibSockHTTPAttrSet.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSockHTTPAttrSet, INetLibSockHTTPReqSend

INetLibSockHTTPReqSend

Purpose

Sends an HTTP request to the remote host or looks for data in the cache.

Prototype

Err INetLibSockHTTPReqSend (UInt16 libRefnum, MemHandle sockH, void *writeP, UInt32 writeLen, Int32 timeout)

Parameters

-> libRefnumRefnum of the Internet library.
-> sockHHandle (allocated by INetLibSockOpen or INetLibURLOpen) of the socket.
-> writePPointer to additional data to send after the request headers. Usually used for POST and PUT operations.
-> writeLenNumber of bytes in writeP.
-> timeoutTimeout in ticks.

Result

0
No error
inetErrRequestTooLong
Request too big
inetErrEncryptionNotAvail
Encryption requested but not available

Comments

This call sends an HTTP request created by INetLibSockHTTPReqCreate and INetLibSockHTTPAttrSet to the remote host. If this is an POST or PUT operation, the data to write can be specified in writeP.

INetLibSockHTTPReqSend doesn't always do network I/O. If the proper socket flag is set, it checks first to see if the requested data is already in the cache. If it is, then a pointer to the cached data is stored in the socket and the socket status is updated to show that data is ready to be read. This will trigger an inetSockReadyEvent event.

The socket flag (inetOpenURLFlagLookInCache) that causes the cache to be checked first can be set via the flags parameter to INetLibURLOpen or by calling INetLibSockSettingSet with the appropriate setting (inetSockSettingFlags).

After sending the request, the application can wait for the response to arrive by either polling INetLibSockStatus until the inputReady boolean is set (not recommended), or by waiting for an inetSockReadyEvent event from INetLibGetEvent (preferred).

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSockHTTPReqCreate, INetLibSockHTTPAttrSet, INetLibGetEvent

INetLibSockOpen

Purpose

Creates and returns a new inet socket handle.

Prototype

Err INetLibSockOpen (UInt16 libRefnum, MemHandle inetH, UInt16 scheme, MemHandle *sockHP)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen.
-> schemeThe protocol scheme to use. Specify one of the INetSchemeEnum types.
<- sockHPPointer to the address where the socket handle is returned.

Result

0
No error
inetErrTooManySockets
Too many sockets open
inetErrSchemeNotSupported
Requested URL scheme not supported

Comments

This call creates a new socket for the given scheme. No network I/O is performed. This is a relatively low level call that can be used in place of INetLibURLOpen when finer control over the socket settings is required.

Using INetLibURLOpen, an HTTP request can be handled with the simple sequence: INetLibURLOpen, INetLibSockRead, and INetLibSockClose. When using INetLibSockOpen, the same HTTP request would be handled by replacing the INetLibURLOpen call with the sequence: INetLibSockOpen, INetLibSockSettingSet (optional), INetLibSockConnect, INetLibSockHTTPReqCreate, INetLibSockHTTPAttrSet (optional), and INetLibSockHTTPReqSend.

The use of INetLibSockOpen allows an application finer control over the socket settings (by calling INetLibSockSettingSet) and the HTTP request headers (by calling INetLibSockHTTPAttrSet).

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibOpen, INetLibURLOpen, INetLibSockRead, INetLibSockClose, INetLibSockSettingSet, INetLibSockHTTPAttrSet

INetLibSockRead

Purpose

Reads data from a socket.

Prototype

Err INetLibSockRead (UInt16 libRefnum, MemHandle sockH, void *bufP, UInt32 reqBytes, UInt32 *actBytesP, Int32 timeout)

Parameters

-> libRefnumRefnum of the Internet library.
-> sockHInet handle allocated by INetLibOpen.
-> bufPPointer to buffer where the data is placed.
-> reqBytesRequested number of bytes.
<- actBytesPPointer to the actual number of bytes read.
-> timeoutTimeout in ticks. Specify evtWaitForever to wait forever.

Result

0
No error

Comments

This call attempts to read reqBytes bytes from the given socket. It returns the actual number of bytes read in *actBytesP. If the connection with the remote host has been closed, *actBytesP contains 0 on exit.

Note that it is normal for the actual bytes read to be less than the requested number of bytes. The application should be prepared to call this routine repeatedly until the desired number of bytes have been read or until *actBytesP contains 0, indicating the connection has been closed, or until an error is returned.

This call returns as much data as possible without blocking, however, if no data is available to be read, it does block until at least one byte is available.

Normally, applications will wait for an inetSockReadyEvent from INetLibGetEvent before calling INetLibSockRead. Alternatively, the application could call INetLibSockStatus to determine if the socket has any data ready (not recommended), or could simply rely on INetLibSockRead to block until at least one byte is available to read. If no data is available before the timeout expires, inetErrReadTimeout error is returned.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibURLOpen, INetLibSockOpen, INetLibSockStatus, INetLibSockClose, INetLibGetEvent

INetLibSockSettingGet

Purpose

Retrieves a socket setting.

Prototype

Err INetLibSockSettingGet (UInt16 libRefnum, MemHandle socketH, UInt16 setting, void *bufP, UInt16 *bufLenP)

Parameters

-> libRefnumRefnum of the Internet library.
-> socketHHandle (allocated by INetLibSockOpen or INetLibURLOpen) of the socket to get a setting from.
-> settingThe setting to get. Specify one of the INetSockSettingEnum values.
<- bufPPointer to buffer where the setting value is to be placed.
<-> bufLenPSize of bufP on entry; size of returned value on exit.

Result

0
No error
inetErrParamsInvalid
Invalid setting requested
inetErrSettingSizeInvalid
*bufLenP is the incorrect size for the requested setting

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSockSettingSet

INetLibSockSettingSet

Purpose

Changes a setting of a socket.

Prototype

Err INetLibSockSettingSet (UInt16 libRefnum, MemHandle socketH, UInt16 setting, void *bufP, UInt16 bufLen)

Parameters

-> libRefnumRefnum of the Internet library.
-> socketHHandle (allocated by INetLibSockOpen or INetLibURLOpen) of the socket to set.
-> settingThe setting to set. Specify one of the INetSockSettingEnum values.
-> bufPPointer to buffer containing the new setting value.
-> bufLenSize of new setting in bufP.

Result

0
No error
inetErrSettingNotImplemented
Invalid setting specified
inetErrSettingSizeInvalid
bufLen is the incorrect size for the setting

Comments

This call can be use to override a general setting for a particular socket.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSockSettingGet

INetLibSockStatus

Purpose

Retrieves the current status of a socket.

Prototype

Err INetLibSockStatus (UInt16 libRefnum, MemHandle socketH, UInt16 *statusP, Err *sockErrP, Boolean *inputReadyP, Boolean *outputReadyP)

Parameters

-> libRefnumRefnum of the Internet library.
-> socketHHandle (allocated by INetLibSockOpen or INetLibURLOpen) of the socket to get status on.
<- statusPPointer to the address where the status is returned. The status will be one of the INetStatusEnum values.
<- sockErrPCurrently unused.
<- inputReadyPPointer to a Boolean; true is returned if the socket has data available to read.
<- outputReadyPPointer to a Boolean; true is returned if the socket can accept data for writing.

Result

0
No error

Comments

Most applications that use INetLibGetEvent will rarely need to use this call since socket status changes are returned in the event structure.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibURLOpen, INetLibSockOpen, INetLibSockRead, INetLibGetEvent

INetLibURLCrack

Purpose

Cracks a URL text string into its components.

Prototype

Err INetLibURLCrack (UInt16 libRefnum, UInt8 *urlTextP, INetURLType *urlP)

Parameters

-> libRefnumRefnum of the Internet library.
-> urlTextPPointer to URL text string.
<-> urlPPointer to address where the URL information block is to be returned.

Result

0
No error
inetErrParamsInvalid
urlTextP is NULL or empty, or urlP is NULL
inetErrURLVersionInvalid
urlP is wrong version

Comments

If a pointer member of urlP is set to NULL on entry, then on exit it will point to the start of that component within the original urlTextP string; the associated member length is set to the length of that URL component. If a pointer member of urlP is not NULL on entry, then it must point to a buffer of sufficient size to hold the member data, and on exit the component string will be copied into this buffer and the associated member length will be updated with the actual size. Note that the returned strings are not null-terminated, so the length values are important.

It's easiest to initialize the InetURLType block to zeros and let this function fill in all the information about the URL components.

The InetURLType block returned from this function has the following structure:

typedef struct { 
UInt16 version; // 0, for future compatibility 
UInt8 *schemeP; // ptr to scheme portion 
UInt16 schemeLen; // size of scheme portion 
UInt16 schemeEnum; // INetSchemeEnum; the scheme 
UInt8 *usernameP; // ptr to username portion 
UInt16 usernameLen; // size of username 
UInt8 *passwordP; // ptr to password portion 
UInt16 passwordLen; // size of password 
UInt8 *hostnameP; // ptr to host name portion 
UInt16 hostnameLen; // size of host name 
UInt16 port; // port number 
UInt8 *pathP; // ptr to path portion 
UInt16 pathLen; // size of path 
UInt8 *paramP; // ptr to param (;param) 
UInt16 paramLen; // size of param 
UInt8 *queryP; // ptr to query (?query) 
UInt16 queryLen; // size of query 
UInt8 *fragP; // ptr to fragment (#frag) 
UInt16 fragLen; // size of fragment 
} INetURLType 

Compatibility

Implemented only if Wireless Internet Feature Set is present.

INetLibURLGetInfo

Purpose

Returns information about a URL.

Prototype

Err INetLibURLGetInfo (UInt16 libRefnum, MemHandle inetH, UInt8 *urlTextP, INetURLInfoType *urlInfoP)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen.
-> urlTextPPointer to URL text string.
<-> urlInfoPPointer to address where the URL information structure is to be returned.

Result

0
No error
inetErrParamsInvalid
urlInfoP is NULL or incorrect version

Comments

The InetURLInfo block returned from this function has the following structure:

typedef struct { 
UInt16 version; // 0, for future compatibility 
UInt16 flags; // flags word 
UInt32 undefined; // reserved for future use 
} INetURLInfo 

The flags word can consist of some combination of these values:

inetURLInfoFlagIsSecure // URL was encrypted 
inetURLInfoFlagIsRemote // URL was retrieved
from the net 
inetURLInfoFlagIsInCache // URL is stored in
the cache 

Compatibility

Implemented only if Wireless Internet Feature Set is present.

INetLibURLOpen

Purpose

Accesses a URL on the Internet or in the cache.

Prototype

Err INetLibURLOpen (UInt16 libRefnum, MemHandle inetH, UInt8 *urlP, UInt8 *cacheIndexURLP, MemHandle *sockHP, Int32 timeout, UInt16 flags)

Parameters

-> libRefnumRefnum of the Internet library.
-> inetHInet handle allocated by INetLibOpen.
-> urlPPointer to string containing the URL to access.
-> cacheIndexURLPPointer to URL string under which the requested URL should be indexed in the cache. Specify NULL if you don't need to index the cache. If you are using the Web Clipping Application Viewer cache (not recommended), you must follow the Viewer convention, which is to pass the URL of the active PQA.
<- sockHPPointer to address where the socket handle is returned.
-> timeoutTimeout in ticks. Specify evtWaitForever to wait forever.
-> flagsFlags indicating caching and encryption options desired. Specify zero, one, or more of the URL open flags (see URL Open Constants).

Result

0
No error
inetErrParamsInvalid
urlP is NULL

Comments

This call sets up a connection to a resource on the Internet addressed by urlP and returns a socket handle. Note that if you specify that the cache should be searched first, and if the data is found in the cache, no network I/O occurs. The application can then read that socket resource through the INetLibSockRead call.

This call is a convenience routine that internally makes the following calls for http URLs: INetLibSockOpen, INetLibSockConnect, INetLibSockHTTPReqCreate, and INetLibSockHTTPReqSend.

This routine returns immediately before performing any required network I/O. It is then up to the caller to either block on INetLibSockRead, or to use INetLibGetEvent to model asynchronous operation. Using INetLibGetEvent is the preferred way of performing network I/O since it maximizes battery life and user-interface responsiveness.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

See Also

INetLibSockOpen, INetLibSockConnect, INetLibSockRead, INetLibSockClose

INetLibURLsAdd

Purpose

Concatenates two URLs, resulting in one absolute URL.

Prototype

Err INetLibURLsAdd (UInt16 libRefnum, Char *baseURLStr, Char *embeddedURLStr, Char *resultURLStr, UInt16 *resultLenP)

Parameters

-> libRefnumRefnum of the Internet library.
-> baseURLStrPointer to base URL string.
-> embeddedURLStrPointer to URL text string to append.
<-> resultURLStrPointer to resulting URL string.
<-> resultLenPPointer to size of resultURLStr buffer on entry. On exit, pointer to resulting URL length (including null terminator).

Result

0
No error

Comments

Used to append a URL fragment to a base URL, resulting in an absolute URL string that can be passed to INetLibURLOpen or other functions. This routine ensures that the resulting string conforms to the URL format.

Compatibility

Implemented only if Wireless Internet Feature Set is present.

INetLibWiCmd

Purpose

Invokes a command that operates on the wireless indicator.

Prototype

Boolean INetLibWiCmd (UInt16 refNum, UInt16 cmd, int enableOrX, int y)

Parameters

-> refNumRefnum of the Internet library.
-> cmdThe command to invoke. Specify one of the WiCmdEnum values (see Comments section).
-> enableOrXIf cmd is wiCmdSetEnabled, specify 1 to enable the wireless indicator or 0 to disable it. If cmd is wiCmdSetLocation, this specifies the x coordinate of the location.
-> yThe y coordinate of the location. Used only if cmd is wiCmdSetLocation.

Result

If cmd is wiCmdEnabled, this function returns true if the wireless indicator is enabled or false if it is not. For other command types, the return value is undefined.

Comments

The wireless indicator is a 19x13 pixel image on the screen to indicate the current wireless signal strength. This shows as 0 - 5 bars. If the application is in a non-modal window with a title bar, the preferred location for the indicator is at (140,1).

It automatically updates itself as long as you are calling INetLibGetEvent. It should be shown on screen while a wireless transaction is in progress. It may also be shown when the user has nothing useful to do next but initiate a wireless transaction, and there isn't much other useful information being displayed.

The WiCmdEnum enum specifies a command that operates on the wireless indicator in the user interface. The definition of this type is found in WirelessIndicator.h and is as follows:

typedef enum { 
wiCmdInit =0, 
wiCmdClear, 
wiCmdSetEnabled, 
wiCmdDraw, 
wiCmdEnabled, 
wiCmdSetLocation, 
wiCmdErase 
} WiCmdEnum; 

Value Descriptions

wiCmdInit
Initializes the wireless indicator. You must invoke this command first, before using any of the others.
wiCmdClear
Applications shouldn't use this command. To erase the indicator, disable it by using wiCmdSetEnabled and passing 0 for enableOrX.
wiCmdSetEnabled
Enables or disables the wireless indicator.
wiCmdDraw
Redraws the wireless indicator using the latest data. Applications don't need to use this command since the indicator is redrawn automatically by INetLibGetEvent.
wiCmdEnabled
Returns a Boolean indicating if the wireless indicator is enabled.
wiCmdSetLocation
Sets the location for the wireless indicator on the screen.
wiCmdErase
Erases the wireless indicator. Applications shouldn't use this command. To erase the indicator, disable it by using wiCmdSetEnabled and passing 0 for enableOrX.

Compatibility

Implemented only if Wireless Internet Feature Set is present.