COMMENT @%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

	Copyright (c) Geoworks 1995 -- All Rights Reserved

PROJECT:	Socket
MODULE:		Access point database
FILE:		accpnt.def

AUTHOR:		Eric Weber, Apr 24, 1995

MACROS:
	Name			Description
	----			-----------

REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	EW	4/24/95   	Initial revision


DESCRIPTION:
	API for defining and accessing Internet access points
		
	$Id: accpnt.def,v 1.1 97/04/04 13:46:02 newdeal Exp $

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%@

SetDef __ACCPNT


StartLibrary accpnt

;
; Each access point has an ID number, which applications should use to
; identify it.  This number does not change over the life of the access
; point, and no two access points have the same ID.  ID numbers are assigned
; sequentially from 1 to 65535.  If an access point is deleted, it's
; ID will not be reused unless all 65535 possible IDs have been exhausted,
; in which case currently unused values starting with 1 again will be
; assigned.
;
; ID 0 will never be assigned.  It is used by the controller and various
; API routines as a canonical invalid ID number.
ACCESS_POINT_INVALID_ID	equ	0

;
; what type of access an access point defines
;
AccessPointType		etype	word,1,1

; standard applications
APT_INTERNET		enum	AccessPointType
APT_TERMINAL		enum	AccessPointType
APT_TELNET		enum	AccessPointType

; a reserved value for one-of-a-kind access points that should
; not appear in any list and are used only within one app
APT_APP_LOCAL		enum	AccessPointType

; new for Lizzy
APT_CALLING_CARD	enum	AccessPointType

; APT_ALL is a wildcard for listing access points, and is never the
; type of a specific access point
APT_ALL			equ	0

;
; some common property strings
;
; Any access point function requesting a property name as a far pointer,
; can also accept a "pointer" with segment=0 and
; offset=AccessPointStandardProperty.  Any APSP can be combined with
; APSP_AUTOMATIC to make an alternative form of the name.  This library
; puts no special interpretation on temporary names, but they are intended
; to represent values which are obtained from automatic configuration and
; not from the user.
;
AccessPointStandardProperty	etype	word,0,2
APSP_NAME		enum	AccessPointStandardProperty
APSP_PHONE		enum	AccessPointStandardProperty
APSP_USER		enum	AccessPointStandardProperty
APSP_SECRET		enum	AccessPointStandardProperty
APSP_ADDRESS		enum	AccessPointStandardProperty
APSP_MASK		enum	AccessPointStandardProperty
APSP_GATEWAY		enum	AccessPointStandardProperty
APSP_DNS1		enum	AccessPointStandardProperty
APSP_DNS2		enum	AccessPointStandardProperty
APSP_DATA_BITS		enum	AccessPointStandardProperty
APSP_STOP_BITS		enum	AccessPointStandardProperty
APSP_PARITY		enum	AccessPointStandardProperty
APSP_DUPLEX		enum	AccessPointStandardProperty
APSP_MODEM_INIT		enum	AccessPointStandardProperty
APSP_BS			enum	AccessPointStandardProperty
APSP_HOSTNAME		enum	AccessPointStandardProperty
APSP_INTERNET_ACCPNT 	enum	AccessPointStandardProperty
APSP_PROMPT_SECRET	enum	AccessPointStandardProperty


APSP_AUTOMATIC	equ	4000h	; see documentation above
APSP_UNDEFINED	equ	-1	; see AccessPointChangeDescription

;
; The _following properties are new for Lizzy
; using these on any pre-Lizzy product will cause a FatalError
;
APSP_USE_LOGIN_APP	enum	AccessPointStandardProperty
APSP_LOGIN_APP_NAME	enum	AccessPointStandardProperty	
APSP_SCRIPT_NAME	enum	AccessPointStandardProperty
APSP_CCARD_NAME		enum	AccessPointStandardProperty
APSP_CCARD_ACCESS	enum	AccessPointStandardProperty
APSP_CCARD_ID		enum	AccessPointStandardProperty
APSP_CCARD_PREFIX	enum	AccessPointStandardProperty
APSP_CCARD_SEQUENCE	enum	AccessPointStandardProperty

APSP_COMPRESSION	enum	AccessPointStandardProperty
APSP_BEARER_CAPABILITY	enum	AccessPointStandardProperty
APSP_LINE_END		enum	AccessPointStandardProperty

;
; New for GPC
;
APSP_USE_DIALING_OPTIONS	enum	AccessPointStandardProperty
    ; Integer value.  If non-zero, indicates that this access point
    ; should use dialer options.

APSP_LOCAL_DIALING_OPTIONS	enum	AccessPointStandardProperty
    ; Integer value of type AccessPointLocalDialingOptions.
    ; These dialing options apply to only this access point.
    ; If this property is not preset, all of its options are assumed
    ; to be off.

AccessPointChangeType	etype	word,0,2
APCT_CREATE		enum	AccessPointChangeType	; access pnt created
APCT_DESTROY		enum	AccessPointChangeType	; access pnt destroyed
APCT_PROPERTY		enum	AccessPointChangeType	; prop value changed
APCT_MULTI_DESTROY	enum	AccessPointChangeType	; >1 accpnts destroyed
	; If change type is APCT_MULTI_DESTROY, the list of
	; deleted IDs is stored as an array of words at APCD_idList.
	; APCD_id is the number of access points.
APCT_LOCK		enum	AccessPointChangeType	; lock status changed


;
; data for GWNT_ACCESS_POINT_CHANGE
;
AccessPointChangeDescription	struct
	; what kind of change occurred
	APCD_changeType		AccessPointChangeType
	; which access point changed, or number of changed points
	APCD_id			word
	; the type of the access point.
	APCD_accessType		AccessPointType
	; standard property, if known; APSP_UNDEFINED if unknown
	; if change type is not APCT_PROPERTY, this field has no meaning
	; and may contain arbitrary values
	;
	; Only known if a standard property was explicitly passed to
	; an accpnt routine.  If a custom string which happens to be the
	; same as a standard property is used, it will not be detected.
	APCD_stdProperty	AccessPointStandardProperty
	; null terminated name of property, if APCT_PROPERTY
	; array of IDs, if APCT_MULTI_DESTROY
	APCD_property		label char
AccessPointChangeDescription	ends

;
; these features are not independent - if one is enabled, all below it
; must also be enabled
;
AccessPointControlFeatures	record
	:5
	APCF_TWOLEVEL:1		; use two-level trigger
	APCF_EDIT:1		; edit, create, and delete triggers
	APCF_LIST:1		; list of access points
AccessPointControlFeatures	end

;
; These types are used in AccessPointSetDialingOptions and
; AccessPointGetDialingOptions.
;
AccessPointDialingMethod	etype byte
	APDM_TONE		enum	AccessPointDialingMethod, 'T'
	APDM_PULSE		enum	AccessPointDialingMethod, 'P'

; These lengths do not include zero byte termination.
;
APDO_AREA_CODE_LEN	equ	3
APDO_CALL_WAITING_LEN	equ	10
APDO_OUTSIDE_LINE_LEN	equ	10

AccessPointDialingOptions	struct
	APDO_areaCode		TCHAR	(APDO_AREA_CODE_LEN+1)		dup(?)
		; NULL terminated area code string
	APDO_callWaiting	TCHAR	(APDO_CALL_WAITING_LEN+1)	dup(?)
		; NULL terminated "disable call waiting" string
	APDO_outsideLine	TCHAR	(APDO_OUTSIDE_LINE_LEN+1)	dup(?)
		; NULL terminated "acces outside line" string
	APDO_dialMethod		AccessPointDialingMethod
		; TONE or PULSE
	APDO_tenDigit		BooleanByte
		; If TRUE, must always dial ten digits
	APDO_waitForDialtone	BooleanByte
		; If TRUE, wait for dialtone
AccessPointDialingOptions	end

AccessPointLocalDialingOptions	record
	:14
	APLDO_OMIT_ONE_FOR_LONG_DISTANCE:1
		; Omit the leading one when dialing long distance.
	APLDO_ALWAYS_ADD_AREA_CODE:1
		; Always dial the area code even if it is the same as the area
		; code in the global dialing options.
AccessPointLocalDialingOptions	end

;
; controller for selecting an access point
;
AccessPointControlClass		class	GenControlClass

MSG_ACCESS_POINT_CONTROL_SET_TYPE		message
; Set the APSI_type instance data
;
; Pass:		cx	= AccessPointType
; Return:	nothing
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_GET_TYPE		message
; Get APSI_type
;
; Pass:		nothing
; Return:	ax	= AccessPointType
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_GET_SELECTION		message
; Get the current selection
;
; Pass:		nothing
; Return:	ax	= selection ID (0 if no selection)
;		carry set if no selection
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_SET_SELECTION		message
; Get the current selection
;
; Pass:		cx	= selection ID
; Return:	carry set if not in list
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_GET_EDIT_MSG		message
; Get the ASPCI_editMsg
;
; Pass:		nothing
; Return:	ax	= edit message
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_SET_EDIT_MSG		message
; Set the ASPCI_editMsg
;
; Pass:		cx	= edit message
; Return:	nothing
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_SEND_EDIT_MSG		message
; Send the edit message to the controller's output
;
; Pass:		cx	= access point to edit
; Return:	nothing
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_GET_ENABLE_DISABLE		message
; Get the ASPCI_enableDisable
;
; Pass:		nothing
; Return:	^lcx:dx	= object to enable
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_SET_ENABLE_DISABLE		message
; Set the ASPCI_enableDisable
;
; Pass:		^lcx:dx = object to enable
; Return:	nothing
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_CHANGING_LEVELS		message
; One of the TwoLevelTrigger objects has been activated.  Set
; or clear ATTR_ACESS_POINT_CONTROL_SECOND_LEVEL_ACTIVE, and switch
; CMI_bitmap with APCI_altBitmap if this is a ComplexMoniker.  Should
; not be used externally.
;
; Pass:		nothing
; Return:	nothing
; Destroyed:	nothing
;

MSG_ACCESS_POINT_CONTROL_UPDATE_SELECTION		message
; Sent by dynamic list when selection is changed by user.  Should never
; be sent from outside the controller.
;
; Pass:		cx = selection index
; Return:	cx = selection ID
; Destroyed:	ax,cx,dx,bp
;

protominor	AccessNewForMultiselection

MSG_ACCESS_POINT_CONTROL_GET_NUM_SELECTIONS		message
;
; Returns the current number of selections in the access point list.
; Returns zero if there is no selection.
;
; Pass:		nothing
; Return:	ax = number of selections
; Destroyed:	cx, dx, bp 
;

MSG_ACCESS_POINT_CONTROL_GET_MULTIPLE_SELECTIONS	message
;
; Returns the current list of selections in the access point list.
; The caller must allocate a buffer for the entries and pass the size
; of the buffer.  If there is insufficient space in the passed buffer
; for the selections, the buffer will not be filled in.  Call
; MSG_ACCESS_POINT_CONTROL_GET_NUM_SELECTIONS if you don't
; know the number of selections beforehand.  If you are using an
; exclusive list in the Access Point Controller, or know that the
; access point list has none or one item selected, an easier way
; to get the selection is to call MSG_ACCESS_POINT_CONTROL_GET_SELECTION.
;
; Pass:		cx:dx	= buffer to hold the accpnt IDs of selections
;		bp	= max number of selections to place in buffer
; Return:	cx:dx	= preserved, filled in with the accpnt IDs of the
;			  selections (the list will not be null-terminated)
;		ax	= number of selections
; Destroyed:	bp
;

protoreset

HINT_ACCESS_POINT_CONTROL_MINIMIZE_SIZE			vardata
; Causes HINT_ITEM_GROUP_MINIMIZE_SIZE to be placed on the dynamic
; list containing the access points.

ATTR_ACCESS_POINT_CONTROL_LIST_MONIKER			vardata lptr.TCHAR
; Pointer to a null-terminated string to be assigned as the moniker of
; the dynamic list.

ATTR_ACCESS_POINT_CONTROL_SELECTION			vardata	word
; Used internally to store the current selection.

ATTR_ACCESS_POINT_CONTROL_SECOND_LEVEL_ACTIVE		vardata
; On a controller with APCF_TWOLEVEL, indicates that the edit buttons
; are active and APCI_defineParent is inactive.  If present when the
; controller is built, the second level will be set usable.  In this
; case, the APCI_defineParent should not be usable.


; ATTR_GEN_CONTROL_APP_UI
; Used internally to clean up two level trigger properly.  Should not
; be used by applications

protominor	AccessNewForMultiselection

HINT_ACCESS_POINT_CONTROL_MULTISELECTABLE		vardata
; Causes the dynamic list containing the access points to be
; non-exclusive.

protoreset

; type of access point to be displayed
APCI_type	AccessPointType		APT_INTERNET

;
; Message sent to output when a value should be edited.
; This message will also be sent out when a value is created new
; and the implementer may need to set default values in this
; case. 
;
; Pass:		cx	= access point ID to edit
; Return:	nothing
; May destroy:	ax,cx,dx,bp
;
APCI_editMsg	word			0

; parent object for the "define" two level trigger
; used only if APCF_TWOLEVEL is set
APCI_defineParent	optr			0

; menu slot in which the trigger should be placed
; used only if APCF_TWOLEVEL is set
APCI_defineSlot		word			0

; object to enable when at least one access point exists
APCI_enableDisable	optr			0

; For controllers with APCF_TWOLEVEL, and which are ComplexMonikers, this
; value will be exchanged with the CMI_bitmap field whenever switching
; between the two levels (i.e. when the "define" or "back" trigger is used)
;
; If the value of this field is zero, the moniker will not be changed.
;
APCI_altBitmap		word			0

AccessPointControlClass	endc

;
; generic API for manipulating properties
;

global	AccessPointCreateEntry:far
global	AccessPointDestroyEntry:far
global	AccessPointDestroyEntryDirect:far

global	AccessPointGetType:far

global	AccessPointSetStringProperty:far
global	AccessPointSetStringPropertyDirect:far
global	AccessPointSetIntegerProperty:far
global	AccessPointSetIntegerPropertyDirect:far

global	AccessPointGetStringProperty:far
global	AccessPointGetStringPropertyDirect:far
global	AccessPointGetIntegerProperty:far
global	AccessPointGetIntegerPropertyDirect:far

global	AccessPointDestroyProperty:far
global	AccessPointDestroyPropertyDirect:far

global	AccessPointGetEntries:far
global	AccessPointCompareStandardProperty:far
global	AccessPointCommit:far

global	AccessPointIsEntryValid:far
global	AccessPointIsEntryValidDirect:far

;
; Routines below this line are not available on Communicators shipped
; before January 1997.
;
global	AccessPointLock:far
global	AccessPointLockDirect:far
global	AccessPointUnlock:far
global	AccessPointUnlockDirect:far
global	AccessPointInUse:far
global	AccessPointInUseDirect:far

global	AccessPointGetActivePoint:far
global	AccessPointSetActivePoint:far
;
; C stubs
;
global  ACCESSPOINTCREATEENTRY:far
global  ACCESSPOINTDESTROYENTRY:far
global  ACCESSPOINTDESTROYENTRYDIRECT:far
global  ACCESSPOINTGETTYPE:far
global  ACCESSPOINTSETSTRINGPROPERTY:far
global  ACCESSPOINTSETSTRINGPROPERTYDIRECT:far
global  ACCESSPOINTSETINTEGERPROPERTY:far
global  ACCESSPOINTSETINTEGERPROPERTYDIRECT:far
global  ACCESSPOINTGETSTRINGPROPERTYBLOCK:far
global  ACCESSPOINTGETSTRINGPROPERTYBLOCKDIRECT:far
global  ACCESSPOINTGETSTRINGPROPERTYBUFFER:far
global  ACCESSPOINTGETSTRINGPROPERTYBUFFERDIRECT:far
global  ACCESSPOINTGETINTEGERPROPERTY:far
global  ACCESSPOINTGETINTEGERPROPERTYDIRECT:far
global  ACCESSPOINTDESTROYPROPERTY:far
global  ACCESSPOINTDESTROYPROPERTYDIRECT:far
global  ACCESSPOINTGETENTRIES:far
global  ACCESSPOINTCOMPARESTANDARDPROPERTY:far
global	ACCESSPOINTCOMMIT:far
global	ACCESSPOINTISENTRYVALID:far
global	ACCESSPOINTISENTRYVALIDDIRECT:far

;
; Routines below this line are not available on Communicators shipped
; before January 1997.
;
global	ACCESSPOINTLOCK:far
global	ACCESSPOINTLOCKDIRECT:far
global	ACCESSPOINTUNLOCK:far
global	ACCESSPOINTUNLOCKDIRECT:far
global	ACCESSPOINTINUSE:far
global	ACCESSPOINTINUSEDIRECT:far

global	ACCESSPOINTGETACTIVEPOINT:far
global	ACCESSPOINTSETACTIVEPOINT:far

;
; New access point functions for handling dialing options.
;
global	AccessPointSetDialingOptions:far
global	AccessPointGetDialingOptions:far
global	AccessPointGetPhoneStringWithOptions:far
;
; And relevant C stubs, of course.
;
global	ACCESSPOINTSETDIALINGOPTIONS:far
global	ACCESSPOINTGETDIALINGOPTIONS:far
global	ACCESSPOINTGETPHONESTRINGWITHOPTIONS:far

EndLibrary accpnt
