
                     -------------------------------------------------------
                               Microdog Suite 64-bit Linux Application
                                    Illustration of DLL sample 
                     -------------------------------------------------------

                 	Copyrights (c)  2012 ,  SafeNet China Ltd. 


===============================
Introduction to DLL programming
===============================

Under 64-bit Linux environment, the MicroDog Dynamic Linking Library can be made through GCC compiler.
One important thing is that, because the DLL is seperated from the protected application, 
the calling interface of DLL functions is then exposed to hacker (because of the nature 
of DLL). Here comes the importance for the hiding of DLL functions' name and function 
calling.  Therefore, we strongly recommend you to use static API Library (such as C API) to 
protect your application other than DLL in general. If DLL method must be used, and the 
strength of the protection comes from the complexity of your own DLL, the software developer 
must make the DLL as complicated as possible. The functions' calling interface of DLL must 
be hidden well, and the functions' names in the DLL should not be relative with the Dog 
operation. The sequence of parameters passing should also be baffling for hackers, and the 
dog operation functions should be merged with your own other DLL functions. 


=========
File list
=========
   File Name        Description
   ------------     -----------------------------
   readme-eng.txt   This guide
   libMhlinuxc.so   The shared library
   gsmh.h           The header file of library interface
   sample <DIR>     Application interface module and calling example (for gcc compiler)   
==============================
The Shared Library Functions
==============================
  The Shared Library here refer to the file libMhlinuxc.so. Include the head file GSMH.H when coding.

  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. 
          
=======================
Use the shared library
=======================
1. Set Library Path:    export LD_LIBRARY_PATH=. 

2. Link the Library:    gcc -o sample -L. -lMhlinuxc sample.c 

3. Execute the Sample Program:    ./sample 

============
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 run the protected application in other computer in Linux 2.4, you should install
   the corresponding device driver for the hardware Dog. Please go into driver directory and first execute
   "make",then execute "make install" to install device driver. 

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