Software
FreePPP Control Icon

FreePPP Control 1.2

Scripting addition for FreePPP 2.6

by Sebastian Kloska
 
Berlin, 6 May 02

About FreePPP Control...

FreePPP Control is a scripting addition which gives Applescript access to the main functions of the FreePPP 2.6 system extension. For more information about FreePPP please visit <http://www.rockstar.com/>. 

History

I've been using the scripting addition "MacPPP Control" by Mark Aldritt to automate my daily PPP access. It allows Applescript to open and close a specific PPP connection and set or ask for current state information's. 

MacPPP Control always worked fine with MacPPP and FreePPP up to version 2.5v2 but the developers of FreePPP changed the API and the structure of the preferences file in a way that it wont function with FreePPP 2.6 which at the time of this writing is available as a part of the GearBox 1.1 software. Having some spare time I started to work on my own replacement for the MacPPP scripting addition based on the public interface for FreePPP 2.6. 

How to install FreePPP Control

Assuming that FreePPP 2.6 and Applescript are properly installed on your computer you just have to place the "FreePPP Control" Scripting Addition in your "Scripting Additions" Folder which should be located in your "System Extensions" Folder. Since version 1.2 "FreePPP Control" comes in two flavous. 
  • A 68k version which should work on both 68k and PPC-Mac's. 
  • A PPC-native version. 
The PPC-native version is not very well tested. If you experience problems with it you should use the 68k-version on your PowerPC Mac. After placing the apropriate version in the "Scripting Additions" folder the new FreePPP Applescript commands are instantly available. You don't have to restart. 
 

What features does it add ?

FreePPP Control adds six new commands and one new class to your Applescript environment. If you're starting your Scripteditor and open the dictionary of FreePPP Control or simply drag the Scripting addition onto it you will get short information's about the newly added features. 

New commands

  • open FreePPP: Attempts to open a FreePPP connection


    • Syntax: open FreePPP

    The command takes no arguments and returns no value. It simply tries to open the current PPP connection with the current settings. If there already is an active connection nothing happens. 

    Note: "open FreePPP" initiates a new connection without waiting for success. If you want to be sure that you have an active connection you have to call "FreePPP is" or "FreePPP state". 
     
     
     

  • close FreePPP: Attempts to close a FreePPP connection


    •  Syntax: close FreePPP hard/soft 

    Tries to close the current connection. If there is none nothing happens. As with "open FreePPP" there is no return value. You have to use the "FreePPP is" command or the    "FreePPP state" verb to check for success. 

    New to v1.1

    The "close FreePPP" verb accepts one optional argument. If you write "close FreePPP hard"  the scripting addition tries to force a hard close the command "close FreePPP soft" just closes the PPP stack without closing the telephone line. If you omit this argument the behavior is determined by the "Allow applications to open connection" button in the FreePPP setup. If this option is turned off closing is equivalent to a hard close.  If the option is turned on it's equivalent to a soft close. 

    Caution: The hard/soft feature is not very well tested. My ISP closes the telephone line on hard and soft closes. Please keep me informed if it works.
     
     

  • FreePPP is: check if FreePPP is connected or not connected
Syntax: FreePPP is connected/not connected

There are two different ways to use the "FreePPP is" command to check for a current connection. If you write "FreePPP is connected" the function returns true if your computer is currently connected otherwise false. A different approach is to ask if the computer is not connected by issuing the "FreePPP is not connected" command. The following statements within the if clause both are executed whenever FreePPP is currently on-line. 
 

if FreePPP is connected then
-- do something very useful
end if

if not FreePPP is not connected then
-- do something even more useful
end if
 
 
  • FreePPP set: set various parameters of FreePPP


    • Syntax: FreePPP set

      the current account/current location/current modem
      to string
    The "FreePPP set" command enables Applescript to manipulate some of the FreePPP settings like the account to use when dialing, the current modem and the present location. It takes two arguments. The first of them has to be introduced by the word "the" and determines the parameter you want to change. The second argument is preceded by "to" and specifies the new value. 

    There is no return value. If the function fails the command returns an error to Applescript and the script gets terminated. Valid arguments for new accounts, locations or modems have to be a part of the corresponding list (see "FreePPP get"). Names are case sensitive. The command also fails if there is a current connection. 

    The following example first checks for FreePPP to be off-line and changes the name of the current modem to "MyBrandNew 56k Modem". 
     

    if FreePPP is not connected then FreePPP set the current modem to "MyBrandNew 56k Modem" end if


    New to v1.2

      When trying to change the current account to one with an invalid OpenTransport configuration FreePPP Control bails out with a "Couldn't create OT TCP/IP Account" error message. See Error Messages for more details.
       
  • FreePPP get: get various information from the FreePPP settings


    • Syntax: FreePPP get

    the current account/current location/current modem
    the list of accounts/list of locations/list of modems     This command is used to query different settings of FreePPP. It takes one argument which is preceded by "the". There are two different classes of properties you can ask for. (1) If you request the name of the current account, location or modem a single string is returned which represents the name as it can be seen in the FreePPP Setup dialog. (2) If you ask for the list of accounts, locations or modems you'll get a list of strings representing valid names to choose from. 

    The next example first determines the name of the current location and shows it in a dialog. Afterwards it'll show the list of valid account names one after the other .

     set the_account to FreePPP get the current account
    display dialog the_account
    --
    set the_list to FreePPP get the list of accounts
    repeat with a in the_list display dialog a end repeat
     
     
  • FreePPP state: get state of the current FreePPP connection


    • Syntax: FreePPP state

    "FreePPP state" returns various information?s about the current PPP connection. The function takes no arguments and returns a record of class FreePPP-State.
     

    New classes

    • Class FreePPP-State: Information about the current PPP connection
      Properties: 
       
      active  boolean  -- are we currently connected ?
      duration  integer  -- Duration of the current connection in seconds
      bytes in  integer  -- Number of bytes in
      bytes out  integer  -- Number of bytes out
      local IP  a list of small integer  -- IP address of your computer
      remote IP  a list of small integer  -- IP of the remote server
    This is the only new class defined by the "FreePPP Control" Scripting Addition. The record contains various information about an active PPP connection (if there is any) and it?s only purpose is to serve as a reply type for the "FreePPP state" command. 

    The boolean value "active" reflects the on-line state of your computer. If it?s false there is no connection. In this case the rest of the properties are not defined and can not be evaluated. Checking the "active" property gives the same result as calling "FreePPP is connected". 

    The "duration" Property contains the number of seconds since the connection has been opened. "bytes in" and "bytes out" are counters holding the number of bytes written to and read from the PPP Server. The properties "local IP" and "remote IP" are lists of four integers which represent the IP of your computer and the server on the other side of the telephone. 

    The following example gets the current FreePPP-State, determines if there currently is a connection and shows the local IP if FreePPP is active. 

      open FreePPP
      set a to FreePPP state
      --
      if active of a then
        set IP to ""
        --
        -- Transform the List into a string with dots
        --
        repeat with b in local IP of a
          set IP to (IP & b as text) & "."
        end repeat
        --
        -- delete the trailing "."
        --
        set IP to items 1 thru ((number of items of IP) - 1) of IP as text
        display dialog IP
      end if
       

    Error Messages

    If something goes wrong the FreePPP Control Applescript addition returns an error message to the scripting system and terminates the script execution. There are (hopefully only) six types of error messages returned by the scripting addition.
     
    • "Neither MacTCP nor OpenTransport seems to be installed on this System."
      FreePPP Control wasn?t able to find any TCP/IP connection stack. Every command will terminate with this message if neither MacTCP nor OpenTransport is installed on your Computer.
       
    • "FreePPP 2.6 or higher is not selected in the TCP/IP control pannel."


      • If OpenTransport is installed but FreePPP 2.6 is not selected as the current connection method some commands will terminate with this error message. "open FreePPP" and "close FreePPP" will fail whereas you?re still able to get and set current settings.
       

    • "Either FreePPP 2.6 is not installed or it's not selected in the MacTCP control pannel."


      • If MacTCP provides the TCP/IP stack all commands require FreePPP to be the current connection method and will abort the script with this message.
       

    • "Command is illegal while FreePPP is connected"


      • You tried to set a new name for account, modem or location while the PPP connection was active. FreePPP Control is not able to change these parameters while on-line.
       

    • "Bad name for [account/location/modem]"
      This message is triggered by an attempt to change the current modem, location or account name to something not listed in the FreePPP settings. Please keep in mind that these names are case sensitive. The best strategy to circumvent this message is to take a name out of the list obtained by the "FreePPP get" command.
       
    • Couldn't create OT TCP/IP Account"


      • FreePPP 2.6 allows you to store some aspects of the OpenTransport configuration with an account (see Options in the Account configuration dialog of FreePPP Setup). When trying to change the current account via FreePPP set account to something associated with a malfomated OT configuration FreePPP Control returns this error message.
       

    Please keep me informed

    I've been testing the program thoroughly but I don't have the time to do this checking on various hardware platforms with different system configurations. Please keep me informed if there is any misbehavior of my program. 

    You can reach me via e-mail under <kloska@mpimp-golm.mpg.de>. 

    FreePPP Control is Freeware

    You may use FreePPP Control free of charge make as many copies as you like and distribute it on a non profit basis as long as it stays bundled with the unaltered documentation. For-profit companies that sell software programs must receive explicit written permission from the author before distributing the program.

    Disclaimer

    I make no warranty whatsoever, either implied or expressed, as to the correct functioning of this software. When using this software, the user assumes all responsibility for any damages caused, directly or indirectly, by its use.
     

    FreePPP, the FreePPP Icon and FreePPP Setup are copyrights owned by the FreePPP Group Inc. GearBox is a trademark of Rockstar Studios Inc. Applescript is a registered trademark of Apple Computer, Inc.

    Download FreePPP Control

    Download FreePPP Control