WARNING! The information in this chapter applies only to a very specific set of Palm, Inc. handhelds such as the Palm VII® running Palm OS® version 3.2 or later. You must check for the presence of the Wireless Internet Feature Set prior to using the Internet Library. Never assume that the Internet Library is present on any given class of handheld.
This chapter provides reference material for the Internet library API:
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.
WARNING! In future OS versions, PalmSource, Inc. does not intend to support or provide backward compatibility for the Internet library API documented in this chapter.
Internet Library Data Structures
INetCompressionTypeEnum Enum
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).
Prototype
typedef enum { inetCompressionTypeNone = 0, inetCompressionTypeBitPacked, inetCompressionTypeLZ77 } INetCompressionTypeEnum;
Constants
-
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 Struct
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()
.
Prototype
#define inetConfigNameSize 32;
typedef struct { Char name[inetConfigNameSize]; } INetConfigNameType, *INetConfigNamePtr;
Fields
INetContentTypeEnum Enum
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).
Prototype
typedef enum { inetContentTypeTextPlain = 0, inetContentTypeTextHTML, inetContentTypeImageGIF, inetContentTypeImageJPEG, inetContentTypeApplicationCML, inetContentTypeImagePalmOS, inetContentTypeOther } INetContentTypeEnum;
Constants
-
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 Enum
The INetHTTPAttrEnum
enum specifies HTTP request and response attributes that are set by INetLibSockHTTPAttrSet()
and returned by INetLibSockHTTPAttrGet()
.
Prototype
typedef enum { inetHTTPAttrWhichPart, inetHTTPAttrIncHTTP, inetHTTPAttrCheckMailHi, inetHTTPAttrCheckMailLo, inetHTTPAttrReqContentVersion, inetHTTPAttrRspSize, inetHTTPAttrResult, inetHTTPAttrErrDetail, inetHTTPAttrReason, inetHTTPAttrContentLength, inetHTTPAttrContentLengthUncompressed, inetHTTPAttrContentLengthUntruncated, inetHTTPAttrContentVersion, inetHTTPAttrContentCacheID, inetHTTPAttrReqSize } INetHTTPAttrEnum;
Constants
-
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 toctpConvNone
. 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 Enum
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.
Prototype
typedef enum { inetSchemeUnknown = -1, inetSchemeDefault = 0, inetSchemeHTTP, inetSchemeHTTPS, inetSchemeFTP, inetSchemeGopher, inetSchemeFile, inetSchemeNews, inetSchemeMailTo, inetSchemePalm, inetSchemePalmCall, inetSchemeMail, inetSchemeMac, inetSchemeFirst = inetSchemeHTTP, inetSchemeLast = inetSchemeMail } INetSchemeEnum;
Constants
-
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 Enum
The INetSettingEnum
enum specifies a setting to be returned or set by the INetLibSettingGet()
or INetLibSettingSet()
calls.
Prototype
typedef enum { inetSettingCacheSize, inetSettingCacheRef, inetSettingNetLibConfig, inetSettingRadioID, inetSettingBaseStationID, inetSettingMaxRspSize, inetSettingConvAlgorithm, inetSettingContentWidth, inetSettingContentVersion, inetSettingNoPersonalInfo, inetSettingUserName, inetSettingLast } INetSettingEnum;
Constants
-
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 Enum
The INetSockSettingEnum
enum specifies a socket setting to be returned or set by the INetLibSockSettingGet()
or INetLibSockSettingSet()
calls.
Prototype
typedef enum { inetSockSettingScheme, inetSockSettingSockContext, inetSockSettingCompressionType, inetSockSettingCompressionTypeID, inetSockSettingContentType, inetSockSettingContentTypeID, inetSockSettingData, inetSockSettingDataHandle, inetSockSettingDataOffset, inetSockSettingTitle, inetSockSettingURL, inetSockSettingIndexURL, inetSockSettingFlags, inetSockSettingReadTimeout, inetSockSettingContentVersion, inetSockSettingLast } INetSockSettingEnum;
Constants
-
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 Enum
The INetStatusEnum
enum specifies the status of the socket. The status is returned in the inetSockStatusChangeEvent
event structure and by the call INetLibSockStatus()
.
Prototype
typedef enum { inetStatusNew, inetStatusResolvingName, inetStatusNameResolved, inetStatusConnecting, inetStatusConnected, inetStatusSendingRequest, inetStatusWaitingForResponse, inetStatusReceivingResponse, inetStatusResponseReceived, inetStatusClosingConnection, inetStatusClosed, inetStatusAcquiringNetwork, inetStatusPrvInvalid = 30 } INetStatusEnum;
Constants
-
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:
URL Info Constants
The inetURLInfoFlag
... constants convey information about a URL and are returned by the function INetLibURLGetInfo()
.
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.
Internet Library Functions
INetLibCacheGetObject Function
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.
Declared In
INetMgr.h
Prototype
Err INetLibCacheGetObject ( UInt16 libRefnum, MemHandle clientParamH, UInt8 *urlTextP, UInt32 uniqueID, INetCacheInfoPtr cacheInfoP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
clientParamH
- Inet handle allocated by
INetLibOpen
. -
→
urlTextP
- Pointer to URL text string to find. If this parameter is
NULL
, thenuniqueID
is used to find the entry. -
→
uniqueID
- Unique ID of the cache entry to find. This value can be obtained by calling
INetLibCacheList()
. This parameter is ignored ifurlTextP
is specified. -
←
INetCacheInfoPtr
- Pointer to a structure where information about the cache entry is returned. See the Comments section for details.
Returns
Comments
The INetCacheInfoPtr
type returned from this function is defined as a pointer to an INetCacheInfoType
structure, which has the following definition:
Prototype
typedef struct { MemHandle recordH; INetContentTypeEnum contentType; INetCompressionTypeEnum encodingType; UInt32 uncompressedDataSize; UInt8 flags; UInt8 reserved; UInt16 dataOffset; UInt16 dataLength; UInt16 urlOffset; UInt32 viewTime; UInt32 createTime; UInt16 murlOffset; } INetCacheInfoType, *INetCacheInfoPtr;
Fields
-
recordH
- Handle to the cache record.
-
contentType
-
encodingType
-
uncompressedDataSize
-
flags
- Unused.
-
reserved
- Reserved for future use.
-
dataOffset
- Offset to content.
-
dataLength
- Size of content.
-
urlOffset
- Offset to URL.
-
viewTime
- Time last viewed.
-
createTime
- Time entry was created.
-
murlOffset
- Offset to master URL.
Compatibility
Implemented only if Wireless Internet Feature Set is present.
INetLibCacheList Function
Purpose
Returns an item from the cache list, based on its URL and index in the list.
Declared In
INetMgr.h
Prototype
Err INetLibCacheList ( UInt16 libRefnum, MemHandle inetH, UInt8 *cacheIndexURLP, UInt16 *indexP, UInt32 *uidP, INetCacheEntryP cacheP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
inetH
- Inet handle allocated by
INetLibOpen
. -
→
cacheIndexURLP
- Pointer 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.
-
↔
indexP
- Pointer 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. -
←
uidP
- Pointer to a long value where the unique ID of the found cache entry is returned.
-
←
cacheP
- Pointer to a structure where information about the found cache entry is returned. See the Comments section for details.
Returns
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 Function
Purpose
Checks the antenna state and displays a dialog asking the user to raise it if it is down.
Declared In
INetMgr.h
Prototype
Err INetLibCheckAntennaState( UInt16 refNum )
Parameters
Returns
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 Function
Purpose
Closes up and frees an inet handle. Closes or decrements the open count of the net library.
Declared In
INetMgr.h
Prototype
Err INetLibClose ( UInt16 libRefnum, MemHandle inetH )
Parameters
Returns
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
INetLibConfigAliasGet Function
Purpose
Determines to which configuration a built-in alias points.
Declared In
INetMgr.h
Prototype
Err INetLibConfigAliasGet ( UInt16 refNum, UInt16 aliasIndex, UInt16 *indexP, Boolean *isAnotherAliasP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
aliasIndex
- Index 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 byINetLibConfigIndexFromName()
. -
←
indexP
- Pointer where the index of the configuration pointed to by
aliasIndex
is returned. 0 is returned ifaliasIndex
does not point to another configuration. -
←
isAnotherAliasP
- If
*indexP
is the index of another alias configuration, this Boolean is set totrue
.
Returns
Compatibility
Implemented only if Wireless Internet Feature Set is present.
See Also
INetLibConfigAliasSet Function
Purpose
Points any of the built-in aliases (".DefWireline", ".DefWireless", etc.) to a given defined configuration.
Declared In
INetMgr.h
Prototype
Err INetLibConfigAliasSet ( UInt16 refNum, UInt16 configIndex, UInt16 aliasToIndex )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
configIndex
- Index 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 byINetLibConfigIndexFromName()
. -
→
aliasToIndex
- Index of configuration that the alias identified by
configIndex
is to point to. Specify 0 to remove an existing alias assignment.
Returns
Compatibility
Implemented only if Wireless Internet Feature Set is present.
See Also
INetLibConfigDelete Function
Purpose
Declared In
INetMgr.h
Prototype
Err INetLibConfigDelete ( UInt16 refNum, UInt16 index )
Parameters
-
→
refnum
- Refnum of the Internet library.
-
→
index
- Index 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 byINetLibConfigIndexFromName()
.
Returns
Compatibility
Implemented only if Wireless Internet Feature Set is present.
See Also
INetLibConfigIndexFromName()
, INetLibConfigList()
INetLibConfigIndexFromName Function
Purpose
Returns the index of a configuration given it's name.
Declared In
INetMgr.h
Prototype
Err INetLibConfigIndexFromName ( UInt16 refNum, INetConfigNamePtr nameP, UInt16 *indexP )
Parameters
-
→
refnum
- Refnum of the Internet library.
-
→
nameP
- Pointer to an
INetConfigNameType
structure that names the configuration whose index you want to get. -
←
indexP
- Pointer where the index of the configuration identified in
nameP
is returned.
Returns
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 Function
Purpose
Returns an array containing a list of the available Internet library network configurations.
Declared In
INetMgr.h
Prototype
Err INetLibConfigList ( UInt16 refNum, INetConfigNameType nameArray[], UInt16 *arrayEntriesP )
Parameters
-
→
refnum
- Refnum of the Internet library.
-
→
nameArray
- Pointer to an array of
INetConfigNameType
structs that is to be filled in by this routine. -
↔
arrayEntriesP
- On 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).
Returns
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 Function
Purpose
Makes the given configuration active without having to close and reopen the Internet library by using INetLibOpen
.
Declared In
INetMgr.h
Prototype
Err INetLibConfigMakeActive ( UInt16 refNum, MemHandle inetH, UInt16 configIndex )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
inetH
- Inet handle allocated by
INetLibOpen
. -
→
configIndex
- Index 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 byINetLibConfigIndexFromName()
.
Returns
Compatibility
Implemented only if Wireless Internet Feature Set is present.
See Also
INetLibConfigSaveAs()
, INetLibConfigList()
, INetLibConfigIndexFromName()
INetLibConfigRename Function
Purpose
Declared In
INetMgr.h
Prototype
Err INetLibConfigRename ( UInt16 refNum, UInt16 index, INetConfigNamePtr newNameP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
index
- Index 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 byINetLibConfigIndexFromName()
. -
→
newNameP
- Pointer to an
INetConfigNameType
structure holding the new name of the configuration. The name cannot start with a period or an underscore.
Returns
Trying to save as an alias (beginning with ".") or as a built-in configuration (beginning with "_"). |
|
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 Function
Purpose
Saves the current network configuration settings under the given name.
Declared In
INetMgr.h
Prototype
Err INetLibConfigSaveAs ( UInt16 refNum, MemHandle inetH, INetConfigNamePtr nameP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
inetH
- Inet handle allocated by
INetLibOpen
. -
→
nameP
- Pointer to an
INetConfigNameType
structure holding the name of the configuration. The name cannot start with a period or an underscore.
Returns
Trying to save as an alias (beginning with ".") or as a built-in configuration (beginning with "_"). |
|
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 Function
Purpose
A replacement for EvtGetEvent
that informs an application of status changes to Internet sockets as well as user interface events.
Declared In
INetMgr.h
Prototype
void INetLibGetEvent ( UInt16 libRefnum, MemHandle inetH, INetEventType *eventP, Int32 timeout )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
inetH
- Inet handle allocated by
INetLibOpen
, orNULL
. -
↔
eventP
- The event structure is returned via this pointer.
-
→
timeout
- Timeout in ticks. Specify
evtWaitForever
to wait forever.
Returns
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 Function
Purpose
Creates a new application inet handle structure. Opens or increments the open count of the net library.
Declared In
INetMgr.h
Prototype
Err INetLibOpen ( UInt16 libRefnum, UInt16 config, UInt32 flags, DmOpenRef cacheRef, UInt32 cacheSize, MemHandle *inetHP )
Parameters
-
→
libRefnum
- Refnum of the Internet library. Pass the value "INet.lib" to
SysLibFind()
to return this refnum. -
→
config
- Indicates the type of network service desired by the application. Returned by
INetLibConfigIndexFromName()
. -
→
flags
- Currently unused; set to 0.
-
→
cacheRef
- Document cache database reference. Obtain this by using one of the
DmOpenDatabase()
... calls. PassNULL
if you don't want to use a cache. -
→
cacheSize
- Maximum size of the document cache (in bytes). This is ignored if you pass
NULL
forcacheRef
. -
←
inetHP
- Pointer to a handle variable.
Returns
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 Function
Purpose
Retrieves current settings for an inet handle.
Declared In
INetMgr.h
Prototype
Err INetLibSettingGet ( UInt16 libRefnum, MemHandle inetH, UInt16 setting, void *bufP, UInt16 *bufLenP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
inetH
- Inet handle allocated by
INetLibOpen
. -
→
setting
- The setting to get. Specify one of the
INetSettingEnum
enumerated types. -
←
bufP
- Pointer to buffer where the return value is to be put.
-
↔
bufLenP
- Size of
bufP
on entry. Size of setting value on exit.
Returns
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 Function
Purpose
Changes a setting for an inet handle.
Declared In
INetMgr.h
Prototype
Err INetLibSettingSet ( UInt16 libRefnum, MemHandle inetH, UInt16 setting, void *bufP, UInt16 bufLen )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
inetH
- Inet handle allocated by
INetLibOpen
. -
→
setting
- The setting to set. Specify one of the
INetSettingEnum
enumerated types. -
→
bufP
- Pointer to the new setting value.
-
→
bufLen
- Size of the value in
bufP
.
Returns
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 Function
Purpose
Declared In
INetMgr.h
Prototype
Err INetLibSockClose ( UInt16 libRefnum, MemHandle socketH )
Parameters
Returns
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 Function
Purpose
Establishes a connection with a remote host.
Declared In
INetMgr.h
Prototype
Err INetLibSockConnect ( UInt16 libRefnum, MemHandle sockH, UInt8 *hostnameP, UInt16 port, Int32 timeou )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
sockH
- Handle (allocated by
INetLibSockOpen
orINetLibURLOpen
) of the socket to connect. -
→
hostnameP
- Pointer to host name string; can be dotted decimal text string.
-
→
port
- Port number, or 0 for default port.
-
→
timeou
- Timeout in ticks. Specify
evtWaitForever
to wait forever.
Returns
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 Function
Purpose
Queries HTTP request header formed by the local host, or the response header information returned by a remote host.
Declared In
INetMgr.h
Prototype
Err INetLibSockHTTPAttrGet ( UInt16 libRefnum, MemHandle sockH, UInt16 attr, UInt16 attrIndex, void *bufP, UInt32 *bufLenP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
sockH
- Handle (allocated by
INetLibSockOpen
orINetLibURLOpen
) of the socket. -
→
attr
- The attribute to get. Specify one of the
INetHTTPAttrEnum
values. -
→
attrIndex
- The attribute index (if any). Currently unused.
-
←
bufP
- Pointer to the address where the result is returned.
-
↔
bufLenP
- Pointer to the size of
bufP
on entry; size of returned value on exit.
Returns
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
INetLibSockHTTPAttrSet Function
Purpose
Adds additional HTTP request headers to an HTTP request in a socket.
Declared In
INetMgr.h
Prototype
Err INetLibSockHTTPAttrSet ( UInt16 libRefnum, MemHandle sockH, UInt16 attr, UInt16 attrIndex, UInt8 *bufP, UInt16 bufLen, UInt16 flags )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
sockH
- Handle (allocated by
INetLibSockOpen
orINetLibURLOpen
) of the socket. -
→
attr
- The attribute to set. Specify one of the
INetHTTPAttrEnum
values. -
→
attrIndex
- The attribute index (if any). Currently unused.
-
→
bufP
- Pointer to additional header text to add.
-
→
bufLen
- Length of
bufP
. -
→
flags
- Flags that control the addition of new headers. Currently unused.
Returns
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 Function
Purpose
Forms an HTTP request for the socket.
Declared In
INetMgr.h
Prototype
Err INetLibSockHTTPReqCreate ( UInt16 libRefnum, MemHandle sockH, UInt8 *verbP, UInt8 *resNameP, UInt8 *refererP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
sockH
- Handle (allocated by
INetLibSockOpen
orINetLibURLOpen
) of the socket. -
→
verbP
- Reserved for future use.
-
→
resNameP
- Pointer to a string holding the name of the resource to get or put.
-
→
refererP
- Pointer to a string holding the name of the referring URL, or
NULL
if none.
Returns
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 Function
Purpose
Sends an HTTP request to the remote host or looks for data in the cache.
Declared In
INetMgr.h
Prototype
Err INetLibSockHTTPReqSend ( UInt16 libRefnum, MemHandle sockH, void *writeP, UInt32 writeLen, Int32 timeout )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
sockH
- Handle (allocated by
INetLibSockOpen
orINetLibURLOpen
) of the socket. -
→
writeP
- Pointer to additional data to send after the request headers. Usually used for
POST
andPUT
operations. -
→
writeLen
- Number of bytes in
writeP
. -
→
timeout
- Timeout in ticks.
Returns
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 Function
Purpose
Creates and returns a new inet socket handle.
Declared In
INetMgr.h
Prototype
Err INetLibSockOpen ( UInt16 libRefnum, MemHandle inetH, UInt16 scheme, MemHandle *sockHP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
inetH
- Inet handle allocated by
INetLibOpen
. -
→
scheme
- The protocol scheme to use. Specify one of the
INetSchemeEnum
types. -
←
sockHP
- Pointer to the address where the socket handle is returned.
Returns
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 Function
Purpose
Declared In
INetMgr.h
Prototype
Err INetLibSockRead ( UInt16 libRefnum, MemHandle sockH, void *bufP, UInt32 reqBytes, UInt32 *actBytesP, Int32 timeout )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
sockH
- Inet handle allocated by
INetLibOpen
. -
→
bufP
- Pointer to buffer where the data is placed.
-
→
reqBytes
- Requested number of bytes.
-
←
actBytesP
- Pointer to the actual number of bytes read.
-
→
timeout
- Timeout in ticks. Specify
evtWaitForever
to wait forever.
Returns
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 Function
Purpose
Declared In
INetMgr.h
Prototype
Err INetLibSockSettingGet ( UInt16 libRefnum, MemHandle socketH, UInt16 setting, void *bufP, UInt16 *bufLenP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→ socketH
- Handle (allocated by
INetLibSockOpen
orINetLibURLOpen
) of the socket to get a setting from. -
→
setting
- The setting to get. Specify one of the
INetSockSettingEnum
values. -
←
bufP
- Pointer to buffer where the setting value is to be placed.
-
↔
bufLenP
- Size of
bufP
on entry; size of returned value on exit.
Returns
Compatibility
Implemented only if Wireless Internet Feature Set is present.
See Also
INetLibSockSettingSet Function
Purpose
Changes a setting of a socket.
Declared In
INetMgr.h
Prototype
Err INetLibSockSettingSet ( UInt16 libRefnum, MemHandle socketH, UInt16 setting, void *bufP, UInt16 bufLen )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→ socketH
- Handle (allocated by
INetLibSockOpen
orINetLibURLOpen
) of the socket to set. -
→
setting
- The setting to set. Specify one of the
INetSockSettingEnum
values. -
→
bufP
- Pointer to buffer containing the new setting value.
-
→
bufLen
- Size of new setting in
bufP
.
Returns
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
INetLibSockStatus Function
Purpose
Retrieves the current status of a socket.
Declared In
INetMgr.h
Prototype
Err INetLibSockStatus ( UInt16 libRefnum, MemHandle socketH, UInt16 *statusP, Err *sockErrP, Boolean *inputReadyP, Boolean *outputReadyP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→ socketH
- Handle (allocated by
INetLibSockOpen
orINetLibURLOpen
) of the socket to get status on. -
←
statusP
- Pointer to the address where the status is returned. The status will be one of the
INetStatusEnum
values. -
←
sockErrP
- Currently unused.
-
←
inputReadyP
- Pointer to a Boolean;
true
is returned if the socket has data available to read. -
←
outputReadyP
- Pointer to a Boolean;
true
is returned if the socket can accept data for writing.
Returns
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()
IINetLibURLCrack Function
Purpose
Cracks a URL text string into its components.
Declared In
INetMgr.h
Prototype
Err INetLibURLCrack ( UInt16 libRefnum, UInt8 *urlTextP, INetURLType *urlP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
urlTextP
- Pointer to URL text string.
-
↔
urlP
- Pointer to address where the URL information block is to be returned.
Returns
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 Function
Purpose
Returns information about a URL.
Declared In
INetMgr.h
Prototype
Err INetLibURLGetInfo ( UInt16 libRefnum, MemHandle inetH, UInt8 *urlTextP, INetURLInfoType *urlInfoP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
inetH
- Inet handle allocated by
INetLibOpen
. -
→
urlTextP
- Pointer to URL text string.
-
↔
urlInfoP
- Pointer to address where the URL information structure is to be returned.
Returns
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 Function
Purpose
Accesses a URL on the Internet or in the cache.
Declared In
INetMgr.h
Prototype
Err INetLibURLOpen ( UInt16 libRefnum, MemHandle inetH, UInt8 *urlP, UInt8 *cacheIndexURLP, MemHandle *sockHP, Int32 timeout, UInt16 flags )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
inetH
- Inet handle allocated by
INetLibOpen
. -
→
urlP
- Pointer to string containing the URL to access.
-
→
cacheIndexURLP
- Pointer 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. -
←
sockHP
- Pointer to address where the socket handle is returned.
-
→
timeout
- Timeout in ticks. Specify
evtWaitForever
to wait forever. -
→
flags
- Flags indicating caching and encryption options desired. Specify zero, one, or more of the URL open flags (see URL Open Constants).
Returns
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 Function
Purpose
Concatenates two URLs, resulting in one absolute URL.
Declared In
INetMgr.h
Prototype
Err INetLibURLsAdd ( UInt16 libRefnum, Char *baseURLStr, Char *embeddedURLStr, Char *resultURLStr, UInt16 *resultLenP )
Parameters
-
→
libRefnum
- Refnum of the Internet library.
-
→
baseURLStr
- Pointer to base URL string.
-
→
embeddedURLStr
- Pointer to URL text string to append.
-
↔
resultURLStr
- Pointer to resulting URL string.
-
↔
resultLenP
- Pointer to size of
resultURLStr
buffer on entry. On exit, pointer to resulting URL length (including null terminator).
Returns
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 Function
Purpose
Invokes a command that operates on the wireless indicator.
Declared In
INetMgr.h
Prototype
Boolean INetLibWiCmd ( UInt16 refNum, UInt16 cmd, int enableOrX, int y )
Parameters
-
→
refNum
- Refnum of the Internet library.
-
→
cmd
- The command to invoke. Specify one of the
WiCmdEnum
values (see Comments section). -
→
enableOrX
- If
cmd
iswiCmdSetEnabled
, specify 1 to enable the wireless indicator or 0 to disable it. Ifcmd
iswiCmdSetLocation
, this specifies the x coordinate of the location. -
→
y
- The y coordinate of the location. Used only if
cmd
iswiCmdSetLocation
.
Returns
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:
Prototype
typedef enum { wiCmdInit =0, wiCmdClear, wiCmdSetEnabled, wiCmdDraw, wiCmdEnabled, wiCmdSetLocation, wiCmdErase } WiCmdEnum;
Constants
-
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 forenableOrX
. -
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 forenableOrX
.
Compatibility
Implemented only if Wireless Internet Feature Set is present.