Point to Point Protocol
-----------------------

The PPP protocol allows a computer to dial into an ISP (Internet
Service Provider) and access the Internet using a standard modem.  This
is probably the most useful feature in this package, considering its the
very first in a series of Protocols in the Protocol Stack.

The PPP protocol is responsible for transmitting and receiving data,
organinzing the received data, and properly dispatching it to higher level
protocols.

Why would you want to have direct access to PPP?  If you have an existing
application, you can use PPP in conjunction with one other protocol to
add Intranet support into your application.  PPP allows you to communicate
with any other computer on the Internet in any way that you want it to.
For example, a business owner wants to be able to access information at work
from home.  If he has Internet access, it would be a fairly simple task
to set up a communications PC at the office which redirects information
using the Internet as a transport medium and onto his computer.  This can be
done a number of ways, 1 - using a custom protocol, or 2 - the communications
PC can act as a WEB server, interpret data and send it as HTML pages to
anyone with a web browser.

Instead of going on into tremendous detail about the uses of PPP and other
Internet Protocols, I will refer you to a good book that should be fairly
easy to find.  The books title is Internet Programming, published by
Jamsa Press.  The first few chapters outline all the protocols that I will
be discussing, along with some good implementation ideas (not to mention
the theory behind it all).





To use PPP in your application, you must have PPP.PAS in your uses statement :

   Uses PPP;

This is only the first step though.  You must also initialize an object and
make callbacks to that object in order to POLL information correctly.  In
conjunction with the GUI units, you can set up a callback to automatically
handle Incoming and Outgoing data.

To initialize the PPP object you must call the Init Constructor.  I have
included a variable name oPPP in the PPP.PAS file which I would recommend
using.  Before initializing the object, you must know the ComPort and Baud
Rate of the communications device.  Here is an example of Initializing the
oPPP object with Com 2, Baud Rate 57600 :

     oPPP.Init(2,57600,NIL);  {The third parameter is currently not used
                               and should always contain NIL}


Once you have initialized the object, you can begin using PPP.  The first
step is to actually dial in to an ISP and login.  There are 2 procedures
which will make this a relatively painless process :

      Terminal
      Dial

To dial an ISP, given the phone number, you would call :

      oPPP.Dial('','',phone_number,'');  {There are 3 parameters in this
                                          call which are currently not
                                          in use.  These will eventually
                                          allow you to call the dial
                                          procedure with username, password
                                          and a script file for automating
                                          the login process}


Once you have called the Dial procedure, you can call the Terminal procedure
if you are using the GUI functions.  This will bring up a window and allow
you to manually log in to the ISP.  When you have completed logging in, pressing
the <ESC> key will begin the PPP negotiation phase to establish a valid
PPP connections.  If you aren't using the GUI, then you must provide a valid
terminal emulator using the MODEM.PAS functions :

         NumChars
         GetChar
         SendChar

These functions are documented in the MODEM.TXT file.

Once a valid PPP connection has been made and an IP address has been assigned,
you may start polling with the Packet_Driver procedure :

        oPPP.Packet_Driver;


This will process any incoming or outgoing data without any more user interaction.

To sum this all up, it's simply a matter of getting connected.  Once you've
gotten connected, there are no hassles aside from calling the Packet_Driver
Procedure to actually handle the data stream.  This Procedure should be executed
as often as possible to avoid overflows in the receiving/transmitting buffers.
If this Procedure doesn't get called often enough, data could be lost, or
memory overflow may occur.

The following section is a reference to all callable/addressable functions and
variables :

-------------------------------------------------------------------------------

Variable   :     use_PFC      (boolean)

Once a successful PPP connection has been established, this field contains
TRUE if Protocol Field Compression is Enabled, and FALSE if it is not.

-------------------------------------------------------------------------------

Variable   :     use_ADFC     (boolean)

Once a successful PPP connection has been established, this field contains
TRUE if Address and Control Field Compression is Enabled, and FALSE if it is
not.

-------------------------------------------------------------------------------

Variable   :     IPADDR       (IPTYPE : Array[1..4] of byte)

Once a successful PPP connection has been established, this field contains
the IP address of the computer in and array of 4 bytes which together form
a 32-bit address.

-------------------------------------------------------------------------------

Variable   :     IPSTRING     (String[16])

Once a successful PPP connection has been established, this field contains
a legible string version of the IP address (0.0.0.0), which can be used to
show the user the IP address that has been assigned to the computer.

-------------------------------------------------------------------------------

Variable    :    Terminate_OK (boolean)

This variable contains TRUE if it ok to call the DONE destructor of the object.
When it is time to close the PPP connection and you wish to call the DONE
destructor, make sure that this field contains a TRUE value.  If it does not,
the connection is still active and has not been terminated properly.

-------------------------------------------------------------------------------

Variable    :    Frame_Size    (word)

This variable contains the maximum packet size to send or receive across the
connection.  If frames passed into the PPP object larger than Frame_Size, they
will be fragmented and sent as multiple packets.

-------------------------------------------------------------------------------

Constructor Init(comport:byte;baudrate:longint;ifunc:proc);

The Init Constructor will initialize a PPP object.  You must pass a valid com
port and baudrate.  The third variable, ifunc, should be left at NIL until
a future version.  The ifunc variable is a pointer to a procedure which allows
additional PPP negotiation features to be implemented (ie Van-Jacobsen
compression etc..).

                   oPPP.Init(2,57600,NIL);

-------------------------------------------------------------------------------

Destructor  Done;

Destroys the PPP object that was created with the Init Constructor.  You should
not call this destructor until the Terminate_OK flag is set to true.

-------------------------------------------------------------------------------

Function    MakePtr(var variable):pbyte;

This Function is used internally, but you may find other uses for it.  If you
pass a variable to MakePtr, it will return a pointer to the object.  It is the
same as calling the built in Addr() Function for Turbo/Borland Pascal except
that the pointer returned is typecasted to a pbyte which is defined as ^byte.

-------------------------------------------------------------------------------

Function    Carrier:boolean;

This function will return TRUE if a carrier is detected on the modem, and FALSE
if no carrier signal is present :

            IsCarrier := oPPP.Carrier;

-------------------------------------------------------------------------------

Procedure   Terminal;  (USE ONLY WITH GUI)

After the modem has been dialed and a carrier has been detected, you can call
the Terminal procedure to handle a manual login.  This Procedure has been added
to provide a manual extension to the GUI functions only, and cannot be used in
conjunction with any other GUI, text or graphical :

             oPPP.Terminal;

-------------------------------------------------------------------------------

Procedure   Dial(username,password,phone,scriptfile:string);

This Procedure will perform the following functions to the modem before
returning to the calling process :

                 AT&F1
                 ATM0
                 ATDT[phone]

This Procedure is not complete as of yet.  A future release of PPP will allow
you to pass a username, password, and valid script file to completely automate
the login process.

To call the Dial procedure, you must have a valid phone number :

                 oPPP.Dial('','',phone_number,'');

After calling this procedure, the most logical course of action is to
continually call the Carrier function until a carrier has been detected or
a set amount of time has elapsed.

------------------------------------------------------------------------------

Procedure   Packet_Driver;

This Procedure must be called in order to poll the data line for incoming data.
It will also handle all outgoing IP/PPP Packets.  This Procedure is the driving
force behind the PPP unit and must be called as ofter as possible in order to
insure efficient data management  :

                 Repeat
                    oPPP.Packet_Driver;
                    {Other functions repeated in succession}
                 Until (Program_Finished);

-------------------------------------------------------------------------------

Procedure   FormatIP (b1,b2,b3,b4:byte; var ipt:iptype);

This Procedure will take 4 bytes and return an IP address in the IPTYPE format :

            Var
              IPAddr : IPTYPE;

              oPPP.FormatIP (101,102,103,4,IPAddr);

-------------------------------------------------------------------------------

Function    IPstr    (ip:iptype):string;

This function will convert the internal IP representation into a string IP
representation  :

             Var
               IPS : string[16];

               IPS := oPPP.IPstr(IPAdr);

-------------------------------------------------------------------------------

Function    ValidIP  (s:string):boolean;

This function verifies a string representation of an IP address.  You must
pass the string IP address :

            valid := oPPP.ValidIP('101.102.103.4');

The function will return TRUE if the address passed is a valid address, FALSE
if it is not.

-------------------------------------------------------------------------------

Function    StoIP(s:string;var IP:iptype):boolean;

This function will convert a string representation of an IP addres to
a valid IP address stored in an array of 4 bytes.  You must pass both
the string IP address and a variable that will contain the new IP address :

            Var
              IPaddr : IPTYPE;

            success := oPPP.StoIP('101.102.103.4',ipaddr);

The function will return true on success, false if an invalid IP address
was supplied.

-------------------------------------------------------------------------------



Simple PPP demonstration :

Program PPPDemo;

Uses PPP,CRT;

Var
 DONE : Boolean;

Begin
  {Initialize PPP and DIAL into ISP}
  oPPP.Init(2,57600,NIL);
  oPPP.Dial('','','444-3504','');

  {Wait until a carrier is detected before continuing}
  repeat until oPPP.Carrier;

  {Call Procedure to handle user input for logging into and enabling
   PPP connection of ISP}
   LOGIN_TO_ISP;  {Dummy Procedure}

   writeln('Your IP Address is : ',oPPP.IPSTRING);
   writeln;

   DONE := False;

   repeat
     oPPP.Packet_Driver;
     {do stuff}
     if keypressed then DONE := TRUE;
   until DONE;
end.




