TheScarms^(tm) AppSentinel - DLL Calling Conventions
(Version 1.5.0)

METHOD: CheckRegistration(strError) As Boolean

FUNCTION:
   Validate the registration information.

CALLING SEQUENCE:

   To determine if the application is registered:

   1 - Set TrialDays and/or TrialRuns property
   2 - Call GetRegistrationInfo
   3 - Call CheckRegistration

   OR to validate a Registration ID:

   1 - Set TrialDays and/or TrialRuns property
   2 - Call GetRegistrationInfo
   3 - Set RegistrationID property
   4 - Call CheckRegistration

INPUTS:
   None

RETURNS:
   True     - Registration information successfully checked
   False    - Registration information not successfully checked
   strError - Reason for returning False

 PROPERTIES SET:
   Property         Condition                   Value
   ---------------- --------------------------- --------------------------
   DaysLeft         Days left in trial period   0 <= DaysLeft <= TrialDays
                    Application is registered   NoExpiration
                    TrialDays is not used       ""
                    Else                        0
   RunsLeft         Runs left in trial period   0 <= RunsLeft <= TrialRuns
                    Application is registered   NoExpiration
                    TrialRuns is not used       ""
                    Else                        0
   Expired          If Registered               False
                    UnRegistered Days/Runs left False
                    Else                        True
   Registered       Application is registered   True
                    Else                        False

                          Top

METHOD: DeleteRegistration(strPassword, strError) As Boolean

FUNCTION:
   Remove all stored registration information.

CALLING SEQUENCE:
   1 - Set FileMask property*
   2 - Set RegistrySubkey property*
   3 - Set UseMACAddress property*
   4 - Set PriorVersion property*
   5 - Call DeleteRegistration
   6 - Must be last method called
   * These properties are cleared by this procedure.

NOTE:
   This should be the last method called prior to destroying this
   object. This method clears the properties required to save
   registration information. If other properties are set or other
   methods invoked, the call to SaveRegistrationInfo in the Terminate
   event may recreated the store registration information.

INPUTS:
   Password - A case and date sensitive password

RETURNS:
   True     - All information successfully deleted
   False    - All information was not successfully deleted
   strError - Reason for returning False

 PROPERTIES SET:
   Property         Condition                   Value
   ---------------- --------------------------- --------------------------
   FileMask         N/A                         ""
   DaysLeft         N/A                         ""
   RunsLeft         N/A                         ""
   Expired          N/A                         True
   InitialRun       N/A                         True
   FirstRunDate     N/A                         ""
   LastRunDate      N/A                         ""
   TotalRuns        N/A                         "0"
   Registered       N/A                         False
   EvaluationID     N/A                         ""
   MachineID        N/A                         ""
   PriorVersion     N/A                         Current Version
   RegistrationID   N/A                         ""
   RegistrySubkey   N/A                         ""
   UseMACAddress    N/A                         False

                          Top

METHOD: GetRegistrationInfo(strError) As Boolean

FUNCTION:
   Retrieve the stored registration information.

CALLING SEQUENCE:
   This MUST be the first method called.

   1 - Set FileMask property
   2 - Set RegistrySubkey property
   3 - Set UseMACAddress property
   4 - Set PriorVersion property
   5 - Set RememberMID property
   6 - Call GetRegistrationInfo

INPUTS:
   None

RETURNS:
   True     - If information was successfully read
   False    - If information was not successfully read
   strError - Reason for returning False

 PROPERTIES SET:
   Property         Condition                   Value
   ---------------- --------------------------- --------------------------
   MachineID        Normal operation            Unique Machine ID
                    Error ""
   EvaluationID     Normal operation            Unique Evaluation ID
                    Else                        ""
   RegistrationID   Application is registered   Registration ID
                    Else                        ""
   InitialRun       First time app was run      True
                    App was previously run      False
                    Error True
   TotalRuns        InitialRun                  1
                    Not InitialRun              Number > 0
                    Error                       Unchanged from prior value
   FirstRunDate     Normal operation            Current date/time
                    Else                        ""
   LastRunDate      Normal operation            Current DateTime
                    Else                        ""
   DaysLeft         If InitialRun               TrialDays
                    Else                        Unchanged from prior value
   RunsLeft         If InitialRun               TrialRuns - 1
                    Else                        Unchanged from prior value

                          Top

METHOD: Register(strPassword, strError) As Boolean

FUNCTION:
   Register the application without first using an evaluation period.

CALLING SEQUENCE:
   1 - Set FileMask property
   2 - Set RegistrySubkey property
   3 - Set UseMACAddress property
   4 - Set PriorVersion property
   5 - Call Register

INPUTS:
   Password - A case and date sensitive password

RETURNS:
   True     - Application was successfully registered
   False    - Application was not successfully registered
   strError - Reason for returning False

 PROPERTIES SET:
   Property         Condition                   Value
   ---------------- --------------------------- --------------------------
   MachineID        Normal operation            Unique Machine ID
                    Else                        Unchanged from prior value
   EvaluationID     Normal operation            Unique Evaluation ID
                    Else                        ""
   RegistrationID   Normal operation            Registration ID
                    Else                        ""
   InitialRun       Normal operation            False
                    Else                        True
   DaysLeft         Normal operation            NoExpiration
                    Else                        Unchanged from prior value
   RunsLeft         Normal operation            NoExpiration
                    Else                        Unchanged from prior value
   Expired          Normal operation            False
                    Else                        Unchanged from prior value
   FirstRunDate     If not set                  Current DateTime
                    Else                        Unchanged from prior value
   TotalRuns        If TotalRuns = 0            "1"
                    Else                        Unchanged from prior value
   Registered       Normal operation            True
                    Else                        False

                          Top

METHOD: SaveRegistrationInfo(strError) As Boolean

FUNCTION:
   Save the registration information.

CALLING SEQUENCE:
   1 - Set FileMask property
   2 - Set RegistrySubkey property
   3 - Set RememberMID property
   4 - Call SaveRegistrationInfo

INPUTS:
   None

RETURNS:
   True     - Registration data successfully saved
   False    - Registration data not successfully saved
   strError - Reason for returning False

 PROPERTIES SET:
   Property         Condition                   Value
   ---------------- --------------------------- --------------------------
   LastRunDate      Normal operation            Current Date/Time
                    Else                        Unchanged from prior value
   TotalRuns        If TotalRuns = 0            1
                    Else                        Unchanged from prior value

                          Top

METHOD: ValidateEvaluationID(strEvaluationID, strError) As Boolean

FUNCTION:
   Validate the syntax of an Evaluation ID.

CALLING SEQUENCE:
   May be called any time. No dependencies.

INPUTS:
   A string containing an Evaluation ID.

   A valid Evaluation ID is a 36 character string of the form:

   "nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn"

where:

       EID(n)  in {-, 0...9, A...F}
   ASC(EID(n)) in {45, 48...57, 65...70}

OUTPUTS:
   strError - Reason for returning False

RETURNS:
   True     - Evaluation ID is valid.
   False    - Evaluation ID is not valid.

                          Top

METHOD: ValidateMachineID(strMachineID, strError) As Boolean

FUNCTION:
   Validate the syntax of an Machine ID.

CALLING SEQUENCE:
   May be called any time. No dependencies.

INPUTS:
   A string containing a Machine ID.

   A valid Machine ID has the form:

       MID(n)  in {0...9, A...Z}
   ASC(MID(n)) in {48...57, 65...90}

OUTPUTS:
   strError - Reason for returning False

RETURNS:
   True     - Machine ID is valid.
   False    - Machine ID is not valid.

                          Top

METHOD: ValidateRegistrationID(strRegistrationID, strError) As Boolean

FUNCTION:
   Validate the syntax of an Registration ID.

CALLING SEQUENCE:
   May be called any time. No dependencies.

INPUTS:
   A string containing a Registration ID.

   A valid Registration ID is a 36 character string of the form:

   "nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn"

where:

       RID(n)  in {-, 0...9, A...Z, a...w}
   ASC(RID(n)) in {45, 48...57, 65...90, 97...119}

OUTPUTS:
   strError - Reason for returning False

RETURNS:
   True     - Registration ID is valid.
   False    - Registration ID is not valid.

                          Top

PROPERTY:  DaysLeft() As String

 FUNCTION:
   Returns the number of days left in the evaluation period.

 CALLING SEQUENCE:
   Set by CheckRegistration, GetRegistrationInfo, DeleteRegistration and
   Register methods.

RETURNS:
   After A Call To     Condition                  Value
   ------------------  -------------------------- --------------------------
   CheckRegistration   Days left in trial period  0 <= DaysLeft <= TrialDays
                       Application is registered  NoExpiration
                       TrialDays is not used      ""
                       Else                       0
   GetRegistrationInfo If InitialRun              TrialDays
                       Else                       Unchanged from prior value
   Register            Normal operation           NoExpiration
                       Else                       Unchanged from prior value
   DeleteRegistration  N/A                        ""

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  EvaluationID() As String

 FUNCTION:
   Returns the Evaluation ID for this application.

 CALLING SEQUENCE:
   Set by GetRegistrationInfo and Register methods
   Cleared by DeleteRegistration method

RETURNS:
   After A Call To     Condition                   Value
   ------------------  --------------------------- --------------------------
   GetRegistrationInfo If InitialRun               EID, See below
                       Not InitialRun              Stored value
   Register            Success                     EID, See below
                       Else                        Unchanged from prior value
   DeleteRegistration  N/A                         ""

   The Evaluation ID is a 36 character string of the form:

   "nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn"

Where:

       EID(n)  in {-, 0...9, A...F}
   ASC(EID(n)) in {45, 48...57, 65...70}

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  Expired() As Boolean

FUNCTION:
   Return a flag indicating if the evaluation period has expired.

CALLING SEQUENCE:
   Set by CheckRegistration, Register and DeleteRegistration.

RETURNS:
   After A Call To     Condition                   Value
   ------------------  --------------------------- --------------------------
   CheckRegistration   Still within trial period   False
                       Else                        True
   Register            Normal operation            False
                       Else                        True
   DeleteRegistration  N/A                         True

RETURN VALUE DATA TYPE:
   Boolean

                          Top

PROPERTY: FileMask (strValue)

FUNCTION:
   Creates the file names which hold the registration data.

CALLING SEQUENCE:
   Must be set before calling GetRegistrationInfo, SaveRegistrationInfo,
   Register or DeleteRegistration methods.

INPUTS:
   A string containing the mask to use to create the file names from. The
   string is truncated and/or expanded to 10 characters and is of the form:

       F(n)  in {!#$%&'()-@[]`_^~, 0...9, A...Z, a...z}
   ASC(F(n)) in {33, 35...41, 45, 48...57, 64...91, 93...122, 126}

PROPERTIES SET:
  None

INPUT VALUE DATA TYPE:
  String

NOTE:
   The recommended length of the FileMask value is 10 characters. The
   FileMask should be unique. If AppSentinel is used in more than one 
   of your applications, use a different mask and RegistrySubKey in 
   each application.

                          Top

PROPERTY:  FirstRunDate() As strValue

FUNCTION:
   Returns the first date/time the application was run.

CALLING SEQUENCE:
   Set by GetRegistrationInfo and Register.
   Cleared by DeleteRegistration

RETURNS:
   After A Call To      Condition                   Value
   -------------------  --------------------------- -------------------------
   GetRegistrationInfo  If InititalRun              Current date/time
                        Else: Stored Value
   Register             Normal operation            Current date/time
                        Else                        ""
   DeleteRegistration   N/A                         "

   FirstRunDate is of the form:

     "dd/mm/yyyy h:mm:ss PM"

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  InitialRun() As Boolean

FUNCTION:
   Returns a flag indicating if this is the first run of this application.

CALLING SEQUENCE:
   Set by GetRegistrationInfo and Register.

RETURNS:
   After A Call To     Condition                   Value
   ------------------  --------------------------- --------------------------
   GetRegistrationInfo If the InitialRun           True
                       Else                        False
   Register            Normal operation            False
                       Else                        Unchanged from prior value
   DeleteRegistration  N/A                         True

RETURN VALUE DATA TYPE:
   Boolean

                          Top

PROPERTY:  LastRunDate() As String

FUNCTION:
   Returns the last date/time the application was run.

CALLING SEQUENCE:
   Set by GetRegistrationInfo and Register.
   Cleared by DeleteRegistration

RETURNS:
   After A Call To      Condition                   Value
   -------------------  --------------------------- -------------------------
   GetRegistrationInfo  If InititalRun              Current date/time
                        Else: Stored Value
   SaveRegistrationInfo Normal operation            Current date/time
                        Else: Stored Value
   Register             Normal operation            Current date/time
                        Else                        ""
   DeleteRegistration   N/A                         ""
   Terminate            N/A                         Current date/time

   LastRunDate is of the form:

     "dd/mm/yyyy h:mm:ss PM"

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  MachineID() As String

FUNCTION:
   Returns the hardware signature based Machine ID.

   Effected by the PriorVersion and UseMACAddress properties.

CALLING SEQUENCE:
   Call after setting the PriorVersion or UseMACAddress properties.
   Set by GetRegistrationInfo and Register methods
   Cleared by DeleteRegistration method

RETURNS:
   After A Call To     Condition                   Value
   ------------------  --------------------------- --------------------------
   GetRegistrationInfo Success                     MID, See below
                       Else                        ""
   Register            Success                     MID, See below
                       Else                        Unchanged from prior value
   DeleteRegistration  N/A                         ""

   The Machine ID is a string value of the form:

       MID(n)  in {0...9, A...Z}
   ASC(MID(n)) in {48...57, 65...90}

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  NoExpiration() As String

FUNCTION:
   Returns the number of days remaining in the evaluation period once this
   application is registered.

CALLING SEQUENCE:
   May call anytime. No Dependencies

RETURNS:
   A string representing the number of days left in the evaluation period
   after the application is registered.

                          Top

PROPERTY:  PriorVersion() As String

FUNCTION:
   Returns a string indicating the prior version of AppSentinel
   to be compatible with when creating Machine IDs.

CALLING SEQUENCE:
   Set by the PriorVersion property.

RETURNS:
   A string of the form:

   "Major.minor"  Example "1.5"

   If not set it defaults to the current version of the DLL. To see the
   DLL 's version, right click it, select Version and use the first 2
   values.

RETURN VALUE DATA TYPE:
   String
                          Top

PROPERTY:  PriorVersion(strValue)

FUNCTION:
   Instructs AppSentinel to create Machine IDs using the logic of the
   specified prior version. Used for backward compatibility.

CALLING SEQUENCE:
   Must be set before calling any method.

INPUTS:
   A string of the form:
   
     "Major.minor"   Example "1.5"
   
   Right click the AppSentinel DLL to be compatible with, select Version 
   and use the first 2 values, including the ".".

PROPERTIES SET:
   If set to a valid value, the UseMACAddress property is set to False.

INPUT VALUE DATA TYPE:
   String

                          Top

PROPERTY:  Registered() As Boolean

FUNCTION:
   Returns a flag indicating if the application is registered.

CALLING SEQUENCE:
   Set by CheckRegistration, Register and DeleteRegistration.

RETURNS:
   After A Call To     Condition                   Value
   ------------------  --------------------------- --------------------------
   CheckRegistration   Application is registered   True
                       Else                        False
   Register            Normal operation            True
                       Else                        False
   DeleteRegistration  N/A                         False

RETURN VALUE DATA TYPE:
   Boolean

                          Top

PROPERTY:  RegistrationID() As String

FUNCTION:
   Returns the Registration ID for this application.

CALLING SEQUENCE:
   Set by GetRegistrationInfo and Register methods
   Cleared by DeleteRegistration method

RETURNS:
   After A Call To     Condition                   Value
   ------------------- --------------------------- --------------------------
   GetRegistrationInfo Application is registered   Registration ID, see below
                       Else                        ""
   Register            Normal operation            Registration ID, see below
                       Else                        Unchanged from prior value
   DeleteRegistration  N/A                         ""

   The Registration ID is a 36 character string of the form:

   "nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn"

where:

       RID(n)  in {-, 0...9, A...Z, a...w}
   ASC(RID(n)) in {45, 48...57, 65...90, 97...119}

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  RegistrationID (strValue)

FUNCTION:
   Sets the Registration ID to use for this application.

CALLING:
   Set RegistrationID property prior to validating registration information
   by calling the CheckRegistration method.

INPUTS:
   A 36 character Registration ID of the form:

   "nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn"

where:

       RID(n)  in {-, 0...9, A...Z, a...w}
   ASC(RID(n)) in {45, 48...57, 65...90, 97...119}

INPUT VALUE DATA TYPE:
   String

                          Top

PROPERTY:  RegistrySubkey (strValue)

FUNCTION:
   Sets the Windows Registry key under HKEY_Local_Machine\Software where
   registration information will be stored.

CALLING SEQUENCE:
   Set before calling GetRegistrationInfo, SaveRegistrationInfo, Register
   or DeleteRegistration methods.

INPUTS:
   A string of the form:

   "YourCompanyName\YourAppTitle"

   For example: "TheScarms\My Application". Include the "\" character.

INPUT VALUE DATA TYPE:
   String

NOTE:
   If AppSentinel is used in more than one of your applications, use a 
   different value for "YourAppTitle" and for the "FileMask" property 
   in each application.

                          Top

PROPERTY: RememberMID() As Boolean

FUNCTION:
   Store the Machine ID along with other registration data instead
   of calculating it every time AppSentinel is instantiated.

CALLING SEQUENCE:
   Set by RememberMID property.

RETURNS:
   True if the MID value is to be stored.

RETURN VALUE DATA TYPE:
   Boolean
                          Top

PROPERTY: RememberMID(blnValue)

FUNCTION:
   Flag indicating if the machine ID should be stored with other
   registration data or calculated every time AppSentinel is
   instantiated.

CALLING SEQUENCE:
   Set prior to calling GetRegistrationInfo or SaveRegistrationInfo
   methods.

INPUTS:
   True  - Store the machine ID with other registration data.
   False - Do not store the machine ID. Calculate it every time.

INPUT VALUE DATA TYPE:
   Boolean

                          Top

PROPERTY:  RunsLeft() As String

FUNCTION:
   Returns the number of runs left in the evaluation period.

CALLING SEQUENCE:
   Set by CheckRegistration, GetRegistrationInfo, DeleteRegistration and
   Register methods.

RETURNS:
   After A Call To     Condition                  Value
   ------------------- -------------------------- --------------------------
   CheckRegistration   Runs left in trial period  0 <= RunsLeft <= TrialRuns
                       Application is registered  NoExpiration
                       TrialRuns is not used      ""
                       Else                       0
   GetRegistrationInfo If InitialRun              TrialRuns - 1
                       Else                       Unchanged from prior value
   Register            Normal operation           NoExpiration
                       Else                       Unchanged from prior value
   DeleteRegistration  N/A                        ""

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  TotalDays() As String

FUNCTION:
   Returns the total number of days the application was installed.

CALLING SEQUENCE:
   Available after calling GetRegistrationInfo.

RETURNS:
   After A Call To     Condition                   Value
   ------------------  --------------------------- --------------------------
   GetRegistrationInfo Success                     LastRunDate - FirstRunDate
                                                     in days.
                       Else                        ""

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  TotalRuns() As String

FUNCTION:
   Returns the total number of runs since the application was installed.

CALLING SEQUENCE:
   Available after calling GetRegistrationInfo.

RETURNS:
   After A Call To     Condition                   Value
   ------------------  --------------------------- --------------------------
   GetRegistrationInfo Initial Run                 1
                       Else                        Number of runs

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  TrialDays() As String

FUNCTION:
   Returns the number of days to allow during the evaluation period.

CALLING SEQUENCE:
   Set by TrialDays property

RETURNS:
   The number of days to allow.

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  TrialDays (strValue)

FUNCTION:
   Sets the number of days to allow during the evaluation period.

CALLING SEQUENCE:
   Set prior to calling CheckRegistration method.

   * Either TrialRuns and/or TrialDays must bre set.

INPUTS:
   Condition Value
   ---------------------------- --------------------------
   To limit the number of days  A number > 0
   No limit on number of days   Leave blank

INPUT VALUE DATA TYPE:
   String

                          Top

PROPERTY:  TrialRuns() As String

FUNCTION:
   Returns the number of runs to allow during the evaluation period.

CALLING SEQUENCE:
   Set by TrialRuns property

RETURNS:
   The number of runs to allow.

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  TrialRuns (strValue)

FUNCTION:
   Sets the number of runs to allow during the evaluation period.

CALLING SEQUENCE:
   Set prior to calling CheckRegistration method*.

   * Either TrialRuns and/or TrialDays must bre set.

INPUTS:
   Condition Value
   ---------------------------- --------------------------
   To limit the number of runs  A number > 0
   No limit on number of runs   Leave blank

 INPUT VALUE DATA TYPE:
   String

                          Top

PROPERTY:  UseMACAddress() As Boolean

FUNCTION:
   Indicates if the MAC Address is used in the Machine ID.

CALLING SEQUENCE:
   Set by UseMACAddress or PriorVersion property.

RETURNS:
   True if the MAC address is used.

   This value is set to False if the PriorVersion property is set
   to a version prior to 1.5.

   Property has no effect if RememberMID property is True.

RETURN VALUE DATA TYPE:
   Boolean

                          Top

PROPERTY:  UseMACAddress (blnValue)

FUNCTION:
   Indicates if the NIC (Network Interface Card's) MAC Address 
   is used when creating the Machine ID. A MAC address is a 
   unique 48 bit number assigned to the NIC by the manufacturer. 

   SETTING THIS PROPERTY IS NOT A GUARANTEE THE MAC ADDRESS
   WILL BE USED. Obtaining a consistent MAC address depends on
   several parameters: the operating system, the NIC card,
   whether NetBios is installed, the network cable being
   connected, Lan Adapter Number (LANA) used, and other factors.

   You should include the address if you are certain these 
   parameters will be stable on your user's computers.

   This value is set to False if the PriorVersion property is set
   to a version prior to 1.5.

 CALLING SEQUENCE:
   Set prior to calling GetRegistrationInfo, Register or
   DeleteRegistration methods.

 INPUTS:
   Value  Effect
   ------ ------------------------------------------------
   True   Machine ID will use MAC address if available.
   False  Machine ID will not use MAC address.

   Property has no effect if RememberMID property is True.

 INPUT VALUE DATA TYPE:
   Boolean

                          Top

PROPERTY:  WindowsPath() As String

FUNCTION:
   Returns the full path to the Windows folder.

CALLING SEQUENCE:
   May be called anytime. No dependencies.

RETURNS:
   A string containing the path.

RETURN VALUE DATA TYPE:
   String

                          Top

PROPERTY:  WindowsSystemPath() As String

FUNCTION:
   Returns the full path to the Windows System folder.

CALLING SEQUENCE:
   May be called anytime. No dependencies.

RETURNS:
   A string containing the path.

RETURN VALUE DATA TYPE:
   String

                          Top

TheScarms^(tm) AppSentinel © Copyright 2002 David Scarmozzino
All Rights Reserved
www.TheScarms.com/AppSentinel