TheScarms AppSentinel DLL Calling Conventions

TheScarms^(tm) AppSentinel - DLL Calling Conventions

CheckRegistration
DeleteRegistration
GetRegistrationInfo
Register
SaveRegistrationInfo
ValidateEvaluationID
ValidateMachineID
ValidateRegistrationID

DaysLeft
EvaluationID
Expired
FileMask
FirstRunDate
InitialRun
LastRunDate
MachineID
NoExpiration
Registered
RegistrationID - Get
RegistrationID - Set
RegistrySubkey
RunsLeft
TotalDays
TrialDays - Get
TrialDays - Set
TrialRuns - Get
TrialRuns - Set
WindowsPath
WindowsSystemPath

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 - Call DeleteRegistration
   4 - Should 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                         ""
   RegistrationID   N/A                         ""
   RegistrySubkey   N/A                         ""

                          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 - 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 value0
   RunsLeft         If InitialRun               TrialRuns - 1
                    Else                        Unchanged from prior value0

                          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 - 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 - 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

                          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.

CALLING SEQUENCE:
   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:  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"

INPUT VALUE DATA TYPE:
   String

                          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:  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:  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