home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The World of Computer Software
/
World_Of_Computer_Software-02-386-Vol-2of3.iso
/
a
/
awnotes.zip
/
AW4API.TXT
< prev
next >
Wrap
Text File
|
1992-12-22
|
22KB
|
542 lines
pcANYWHERE IV Programmer's Interface
The pcANYWHERE IV Application Programmer's Interface (API)
makes it possible for a user's program to interact with and
possibly modify the operation of pcANYWHERE IV. The programmer's
interface is intended for use by programmers with experience
in IBM PC assembly language.
pcANYWHERE IV API functions are invoked from assembly language
by issuing a far call to the pcANYWHERE IV API entry point with
a function number in the AX register and other parameters in
various registers. The status of the function is returned in
the AX register. Before a program may call the pcANYWHERE IV
API, it must first determine the entry point. This is accomplished
by issuing a DOS INT 21H "Set Date" function to set a specific
invalid date (as described below). If pcANYWHERE IV is not resident,
DOS will simply return an invalid function error code. If pcANYWHERE
IV is resident, it will intercept the function and return the value
'OK' or 'ok' in the AX register and the API entry point in CX:DX.
The following is a sample program that determines if pcANYWHERE IV
is resident and if so, displays its current status:
dseg segment para public 'DATA'
AW4_Address dd 0 ;Place to store pcANYWHERE IV API entry point
NoAW4 db 13,10,'pcANYWHERE IV is not resident.',13,10,'$'
AW4Active db 13,10,'pcANYWHERE IV is active.',13,10,'$'
AW4Ready db 13,10,'pcANYWHERE IV is ready for a connection.',13,10,'$'
AW4Idle db 13,10,'pcANYWHERE IV is inactive.',13,10,'$'
dseg ends
stack segment para stack 'STACK'
dw 200H dup (0)
stack ends
cseg segment para public 'CODE'
assume cs:cseg, ds:dseg, ss:stack
main proc far
push ds ;Put return to DOS on stack
xor ax,ax
push ax
mov ax,dseg ;Set DS to our data segment
mov ds,ax
call near ptr Find_AW4 ;See if pcANYWHERE IV is resident
jz AW4_Resident ;Continue if so
mov dx,Offset NoAW4 ;If not, point to not resident message
jmp Display_Status ;Go display status and exit
AW4_Resident:
mov word ptr AW4_Address,dx ;Save pcANYWHERE IV API entry point
mov word ptr AW4_Address+2,cx
mov ax,2 ;Function number to get pcAW4 status
call AW4_Address ;On return, AH=operating mode, AL=status
mov dx,Offset AW4Active ;Point to pcANYWHERE IV is active message
test al,1 ;If bit 0 of AL is set, session is active
jnz Display_Status ;Jump if so
mov dx,Offset AW4Ready ;Point to pcANYWHERE IV is ready message
cmp ah,2 ;Check for mode=2, "allow incoming calls"
je Display_Status ; Jump if so
mov dx,Offset AW4Idle ;Must be in "hot key activates" mode
Display_Status:
mov ah,9 ;DOS function to display a string
int 21H ;Display the status message
ret ;Return to DOS
main endp
;
; This routine determines if pcANYWHERE IV is resident
; and returns with the Z flag set if so, or clear if not.
;
; We will check for pcANYWHERE IV by issuing a DOS INT 21H function
; to set the date to a specific invalid date. If pcANYWHERE IV is not
; resident, DOS will return with an invalid date error code.
; If pcANYWHERE IV is present, it will intercept the call and return
; with the value 'OK' in the AX register, and its entry point in CX:DX.
; (Note: If the small version of the pcANYWHERE IV/LAN host is resident,
; it will return with AX set to 'ok' in lowercase.)
;
Find_AW4 proc near
mov ah,2BH ;DOS INT 21H set date function number.
mov al,'D' ;Load registers with pcANYWHERE IV signature.
mov bx,'MA' ; The values loaded into the registers
mov cx,'pc' ; are not a valid date and DOS will return
mov dx,'AW' ; with AL = 0FFH if pcANYWHERE IV is not
int 21H ; resident.
cmp ax,'OK' ;Is pcANYWHERE IV resident ?
je FIND_AW4_EXIT ; If so, return, Z flag is set
cmp ax,'ok' ;Set Z flag if a "small" host is resident
Find_AW4_Exit:
ret ;If pcANYWHERE IV is resident, Z flag is set
; and CX:DX has its entry point.
Find_AW4 endp
cseg ends
end main
The pcANYWHERE IV API functions are divided into two groups:
1) general functions and 2) communications functions.
All functions are passed a function number and return
status in the AX register.
For general functions, additional parameters, if required,
are passed to the function in a buffer pointed to by DS:SI
and additional return information is placed in a buffer
pointed to by DS:DI. All registers are preserved.
For communications functions, additional parameters are
passed in BX and CX. DS, ES, DI, SI and BP are preserved.
The functions supported by the pcANYWHERE IV API are as follows:
General functions
Function number Description
--------------- --------------------------------------------
0000H Get pcANYWHERE IV version
0001H Initialize pcANYWHERE IV operation
0002H Get pcANYWHERE IV status
0003H Suspend remote screen updates
0004H Resume remote screen updates
0005H End current remote access session
0006H Remove pcANYWHERE IV from memory
Communications functions
Function number Description
--------------- --------------------------------------------
8000H Read data from communication channel
8001H Write data over communication channel
8002H Get connection status
Note: The communications functions (8000H-8002H) should only
be used after function 0003H has been called to suspend
pcANYWHERE IV.
Function descriptions:
============================================================================
Function 0000H - Get pcANYWHERE IV version
Calling parameters:
AX = 0000H
DS:DI = Pointer to a 1 byte reply buffer where the
host type code is to be placed.
Returns:
AH = Version number
AL = Revision number
DS:DI = Pointer to host type code
0 - host is a full featured host
1 - host is a limited feature LAN host
Description:
This function returns pcANYWHERE IV's version
and revision number as well as a host type code.
This function should be used to determine if
the resident host can support the pcANYWHERE IV
functions that your program will be using.
IMPORTANT NOTE!
If the byte returned at DS:DI is not a 0 or a 1,
your program should refrain from making additional
API calls. Values greater than 1 are reserved for
custom versions of pcANYWHERE IV which may NOT
fully support the programmer's interface. Issuing
the API call's described here when the host type
code is not a 0 or a 1 could result in the host
PC hanging.
============================================================================
Function 0001H - Initialize pcANYWHERE IV operation
Calling parameters:
AX = 0001H
DS:SI = Pointer to request structure formatted as follows:
BYTE Operating mode
0 = Wait for a call
1 = Hot key activates
2 = Incoming call activates
3 = Initiate a call
BYTE[3] User ID to append to config file names
WORD DS relative pointer to path for config files
WORD DS relative pointer to path for program files
Returns:
AX = Status of function
0000H - Function completed successfully
FFFDH - The specified operating mode is invalid
FFFCH - A remote access session is active
FFFAH - The configuration file could not be found
FFF9H - The configuration file is invalid
FFF7H - The communications driver type specified in the
configuration file is different than the one
loaded when pcANYWHERE IV was initially started.
Once the pcANYWHERE IV host has been loaded, the
driver type may not be changed. If a different
driver needs to be loaded, pcANYWHERE IV must
first be removed from memory.
FFF6H - The host operator aborted the function
FFF5H - The communications device could not be initialized
The reason for initialization failure depends
on the type of device. If the device is a software
driver (IPX, NetBIOS, etc), then the required
interface software is probably not installed (IPX,
NetBIOS, etc.). If the device is a local serial
port, then the COM port did not respond to a
standard hardware test. If the device is NASI or
NCSI, either the NASI/NCSI driver is not installed
or the specified port could not be found.
FFF4H - Modem initialization failed (no modem response)
FFF3H - Modem configuration is invalid (corrupt config)
FFF2H - Unable to establish a connection when operating
mode is "Initiate a call"
Description:
This function causes pcANYWHERE IV to load a new
configuration and set its operating mode according
to the mode specified. If the operating mode specified
is 0 (Wait for a call), this function will not return
until the host operator cancels the function by pressing
<Esc> or until a valid connection is established.
If the function is not successful, the operating mode
will be changed to 1 (Hot key activates).
============================================================================
Function 0002H - Get pcANYWHERE IV status
Calling parameters:
AX = 0002H
Returns:
AH = Current operating mode
0 = Wait for a call
1 = Hot key activates
2 = Incoming call activates
AL = Current connection status, where:
Bit 0 = 1 A physical connection is active
Bit 1 = 1 Remote screen updating is active
Bit 2 = 1 Connection checking is active
Bit 3 = 1 Hot key detection is active
Bit 4 = 1 Background file transfer is active
Notes:
The following table lists the possible bit combinations
in the connection status byte:
Value pcANYWHERE IV status
----- ----------------------------------------
08H No connection, hot key activates
0CH No connection, hot key or call activates
01H Connection active, remote user is
logging in or pcANYWHERE IV has been
suspended via API function 3
03H Connection active, screen updates active
11H Connection active, background transfer active
pcANYWHERE IV will set the connection status to 00H while
it is initializing, removing itself from memory or when it
is in "Wait for a call" mode. If initialization or cancelling
fails, the connection status will be changed to 08H and the
operating mode will be set to 1 (Hot key activates). The
only time a connection status of 00H could be returned by
this function is if the function is called from an interrupt
service routine while pcANYWHERE IV is performing one of
the above mentioned tasks.
============================================================================
Function 0003H - Suspend remote screen updates
Calling parameters:
AX = 0003H
Returns:
AX = 0000H - Function completed successfully
FFFBH - A session is not active or has
already been suspended
Description:
This function suspends pcANYWHERE IV's remote screen
updating, allowing a user's application to perform I/O
through the communications device that pcANYWHERE IV
is using. The file transfer program, AWSEND, uses this
function to suspend pcANYWHERE IV while it is transfering
files with the remote computer. While pcANYWHERE IV is
in a suspended state, it will not peform any communications
I/O and it will not check for loss of connection. It is
the responsibility of your application program to check
for loss of connection (see API function 8002H) when
pcANYWHERE IV has been suspended. If the connection is
lost, your application should resume pcANYWHERE IV. Once
resumed, pcANYWHERE IV will detect the connection loss
and prepare for another connection.
============================================================================
Function 0004H - Resume remote screen updates
Calling parameters:
AX = 0004H
Returns:
AX = 0000H - Function completed successfully
FFFBH - A session is not active
Description:
This function causes pcANYWHERE IV to resume remote screen
updating after it has been suspended by API function 3.
Since suspending pcANYWHERE IV can cause the host and remote
screens to be out of sync, this function will automatically
refresh the remote screen.
============================================================================
Function 0005H - End current remote access session
Calling parameters:
AX = 0005H
DS:SI = Pointer to request structure formatted as follows:
BYTE Operating mode
00H = Wait for a call
01H = Hot key activates
02H = Incoming call activates
80H = Use current mode
FFH = Remove from memory
Returns:
AX = Status of function
0000H - Function completed successfully
FFFBH - A session is not active
FFF6H - The host operator aborted the function
FFF4H - Modem initialization failed (no modem response)
Description:
This function terminates the current remote access session
and re-initializes pcANYWHERE IV to the specified operating
mode. (See function 6 for notes on removing pcANYWHERE IV
from memory.) If the specified operating mode is invalid,
the current operating mode will be used.
============================================================================
Function 0006H - Cancel pcANYWHERE IV and remove it from memory
Calling parameters:
AX = 0006H
Returns:
AX = Status of function
0000H - Function completed successfully
FFD2H - Unable to release allocated memory
FFD1H - Unable to release trapped interrupt vectors
Description:
This function terminates the current remote access
session (if one is active) and removes pcANYWHERE IV
from memory if possible. In order for pcANYWHERE IV to
remove itself from memory, it must be able to restore
all of the interrupt vectors it has trapped to their
original values and the memory block in which it resides
must be a valid DOS memory block. If pcANYWHERE IV
reports that it could not release its memory, either
the DOS memory allocation tables have been corrupted
or pcANYWHERE IV was not loaded into memory by DOS. If
one or more of the interrupt vectors that pcANYWHERE IV
has trapped is not currently pointing to pcANYWHERE IV's
service routine for that interrupt, pcANYWHERE IV will
not restore any of the vectors and will not remove
itself from memory. This situation could occur if other
TSR's are loaded after pcANYWHERE IV or if this function
is called from an application that has trapped interrupt
vectors.
============================================================================
Function 8000H - Read data from communication channel
Calling parameters:
AX = 8000H
DS:BX = Pointer to buffer for received data
CX = Buffer size or 0 to get count of characters available
Returns:
AX = Number of characters read or avaiable
0 - No data available
>0 - Character count
<0 - Error
Description:
This function reads data from pcANYWHERE IV's communication
channel and places it in the buffer at DS:BX. As many
characters as are available up to the buffer size will
be copied to the destination buffer. If the buffer size
passed to this function in the CX register is 0, the number
of bytes available for reading will be returned without
copying any data. For example, if your application expects
exactly 10 characters to be received, it may call this
function repeatedly with CX=0 until a value of 10 or greater
is returned. Once it is known that at least 10 characters
are available, it may then issue a call to this function
with CX=10 to read the required 10 bytes. Using this
method simplifies the task of reading a specific number
of characters by eliminating the need for the application
to maintain its own buffer count and pointer.
Under normal operation, error codes should not be returned.
If an error code is returned (high bit of AX=1), a serious
problem exists in the communications driver and your program
should assume that the connection has been lost.
============================================================================
Function 8001H - Write data over communication channel
Calling parameters:
AX = 8001H
DS:BX = Pointer to buffer containing data to write
CX = Number of characters in buffer
Returns:
AX = Number of characters written
0 - No characters written
>0 - Character count
<0 - Error
Description:
This function causes the data in the specified buffer to
be placed in the communications driver's transmit buffer.
If the driver cannot accept all of the data, it will take
as much as it can and return the number of characters
accepted (0 if its buffer is completely full).
As with the read data function, this function should never
return an error. If it does, your application should
assume that the connection has been lost and should
resume pcANYWHERE IV so that it may attempt to prepare
for a new connection.
============================================================================
Function 8002H - Get connection status
Calling parameters:
AX = 8002H
Returns:
AX = Connection status
>0 - Connection active
0 - Connection lost
<0 - Error
Description:
This function returns the state of the logical connection
between the host and remote. The type of device in use
and the "Connection ended by" selection specified in the
configuration determine how loss of connection is detected.
For network devices, this function returns the true state
of the logical connection. For serial devices, this function
returns the state of the signal selected in the "Connection
ended by" selection. If "Always connected" is selected,
this function will always return a non-zero value in AX.
============================================================================
