                     -------------------------------------------------------
	                         MicroDog 64-bit LINUX Application
                                         API Guide to C/C++
                     -------------------------------------------------------

                   		Copyright (c) 2012, SafeNet China Ltd.

=========
File list
=========
   File name             Description
   README-ENG.TXT        This file
   mhlinuxc.o		 The interface module file
   gsmh.h		 The head file of interface module
   sample <DIR>          Application interface module and calling example
                         (for gcc compiler)
=============
API Functions
=============
  The APIs here refer to the file mhlinuxc.o. Include the head file GSMH.H when coding.

1. API define the following functions which can be used in the developer's program.
       unsigned long  DogCheck(void);
       unsigned long  ReadDog(void); 
       unsigned long  WriteDog(void);
       unsigned long  DogConvert(void);
       unsigned long  GetCurrentNo(void);
       unsigned long  SetPassword(void);
       unsigned long  SetDogCascade(void);

2. Developers must define the following global variables in their application:
       unsigned char DogCascade;      
       short  DogAddr;      
       short  DogBytes;            
       unsigned long DogPassword;
       unsigned long NewPassword;
       unsigned long DogResult; 
       void  * DogData;   

   Explanation for global variables
   --------------------------------
     a. DogAddr:  Indicates the start address (0~199) of MicroDog internal 
                  user area during read operation. The sum of adding DogAddr with 
                  DogBytes will not be allowed to be over 200.

     b. DogBytes: Byte number of read operation (1~200) or conversion operation 
                  (1~63). In read operation, The sum of adding DogAddr with DogBytes 
                  will not be allowed to be over 200.

     c. DogPassword: Access password. The factory setting in the hardware Dog is 
                     0, it may be changed by dogedit in UTILITY folder. It 
                     will only take effect for the functions of ReadDog and WriteDog, 
                     not for DogCheck and DogConvert.

     d. DogResult: Result after conversion. Function DogConvertT will put the 
                   converted result into this variable. Be careful, if the 
                   operation of DogConvert fails, the original DogResult value will 
                   not be changed. 

     e. DogCascade:  parameter for cascade capability, it must be equal the number saved in 
                  the Hardware Dog.The DogCascade is the number from 0 to 15. 

     f. DogData: Buffer of read/write/conversion operation. 

		 g. NewPassword: New password to set.

3. unsigned long DogCheck(void)
   Input parameter: DogCascade
   Output parameter: None
   Return value: Returns zero if successful; returns an error code if the function fails.
   Function: Checks whether the hardware Dog exists.  Only a Dog that has the same serial
             number as the OBJ file can be detected.  In this version, the modules have a 
             cascade function. DogCascade must be equal the number saved in Hardware Dog.       
    
4. unsigned long ReadDog(void)
   Input parameter:  DogCascade DogAddr, DogBytes, DogData, DogPassword
   Output parameter:  DogData
   Return value:     0 = operation succeeded. All others are error codes.
   Function: Reads data from the hardware Dog. The Dog contains a 200-byte nonvolatile 
         memory.  ReadDog reads data from the Dog memory beginning at the address 
         indicated by DogAddr.  The bytes number of the read data is indicated 
         by DogBytes.  The read data is stored in the space DogData points to.
         MicroDog verifies the DogPassword. DogPassword is the password for
         read/write operations stored on the hardware Dog.  It can be set by the 
         utility tool DOGEDIT in UTILITY folder .Applications must ensure enough 
         space to buffer the data being read.  ReadDog does not check whether the
         buffer size is sufficient.

5. unsigned long WriteDog(void)
   Input parameter: DogCascade, DogAddr, DogBytes, DogData, DogPassword
   Output parameter: None
   Return value: Returns zero if successful; returns an error code if the function fails.
   Function: Writes data to the hardware Dog. Carries out the same operation as ReadDog,
      except that the data flow direction is different.

*Caution:
     The last 4 bytes are used to define the conversion algorithm. Therefore, better
     not use these 4 bytes unless you want to change the algorithm.

6. unsigned long DogConvert(void)
   Input parameter: DogCascade, DogBytes, DogData
   Output parameter: DogResult
   Return value: Returns zero if successful; returns an error code if the function fails.
   Function: Transfers data to MicroDog.  The hardware Dog converts the data 
       and returns the converted result Dogresult as a 32-bit integer.  DogBytes indicates
       the number of bytes of the date, which DogData points to, being converted. 
       The conversion algorithm can be specified by the developer.  The last 4 bytes 
       of memory affects the conversion algorithm.  The 196th byte is used to 
       specify the algorithm.  Therefore, a developer can define 256 kinds of algorithms. 
       The algorithm descriptors are made up of the 197th, 198th and 199th byte, so it have 
       a maximum of 16,777,215 different combinations.
         

7. unsigned long GetCurrentNo(void)
   Input Parameter: DogCascade, DogData
   Output parameter: DogData
   Return value: Returns zero if successful; returns an error code if the function fails.
   Function: Reads the Manufacturing code of the hardware Dog.Some of the hardware
             Dogs may have the same ID, but every hardware Dog has its unique
             Manufacturing code. The Manufacturing code can help developers manage
             user accounts.
             The Manufacturing code is 4 bytes.

8. unsigned long SetPassword(void)
   Input parameter: DogCascade, DogPassword, NewPassword
   Output parameter: None
   Return value: Returns zero if successful; returns an error code if the function fails.
   Function: Modifies the Dog password.DogPassword is the current password, and NewPassword
             is the one that would replace it.


9. unsigned long SetDogCascade(void)
    Input parameter: DogCascade, DogPassword, DogData
    Output parameter: None
    Return value: Returns zero if successful; returns an error code if the function fails.
    Function: Set the DogCascade. The new cascade is put into the DogData. 
          
============
Error code
============
   Refer to ERRCODE.TXT in the root of the installation directory for detailed 
   information about error codes.

=========
Cautions
=========
1. When you write data to the Dog, changing the last 4 bytes of the 
   MicroDog memory will affect the result of function DogConvert().

2. If you want to release your protected programs to your end-users, please include
   the device drivers and installing tool in the DRIVER folder in your SETUP process,
   and execute installing the device drivers for the Dog first. 

3. If you want to use sample program, please follow these steps:
   (1) Compile the sample program:
       gcc -o sample sample.c mhlinuxc.o
   (2) Run the sample program:
       ./sample

