Chapter Five -- Rockey4ND API |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The Rockey4ND Application Programming Interface (API) is the most flexible and powerful means of protecting your software. The security level of your software is determined by how you implement the API. The API set has been simplified and is intended to make the Rockey4ND programming effort as effective as possible. API encryption enables you to call Rockey4ND in your application to enhance its security level. You may check the existence of the dongle anywhere in your application and take actions as a result of the check. You may also check the data you stored in the UDZ. You may use the Editor program to set and write data to the modules, write algorithms to the User Algorithm Zone (UAZ), user information to the User ID zone (UID) or take other actions. All such operations may be performed with the API. 1.Rockey4ND Function Prototype and Definition WORD Rockey FEITIAN provides developers with a unified function from which they can employ all Rockey4ND operations. This function is defined as a multi-function function. Below is a call example for C language, and we will discuss future applications in a similar way. retcode = Rockey(function,handle,lp1,lp2,p1,p2,p3,p4,buffer); The “Rockey4ND” function parameters are defined as:
Note: All interface parameters must be defined in your program. Rockey4ND cannot transfer NULL or 0 pointers. Use of Null or 0 pointers in your program will generate an error. a)“function” is a 16-bit number. It stands for the specific function and it is defined below:
b ) “handle” is the pointer for Rockey4ND operation’s handle. 2.Rockey4ND API Services Here we discuss the API services in detail. The following functions marked with [*] require the two Advanced passwords. Note: p3 and p4 are Advanced passwords. They are for developers to operate on the dongle. The Advanced passwords should not appear in the software you offer to your customers and you should set the two Advanced passwords “0” when searching for dongles in your application. 2.1) Find a Rockey4ND dongle (RY_FIND) Objective: To check if a specific Rockey4ND is attached to the USB port. Input parameters: function = RY_FIND Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will write the Rockey4ND Hardware ID (HID) to *lp1. 2.2) Find the Next Rockey4ND dongle (RY_FIND_NEXT) Objective: To check if another specific Rockey4ND is attached to the USB port. function = RY_FIND_NEXT Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will write the Rockey4ND Hardware ID (HID) to *lp1. 2.3) Open the Rockey4ND dongle (RY_OPEN) Objective: To open a Rockey4ND dongle with specified passwords or hardware ID. Input parameters: function = RY_OPEN Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will write the handle address to the *handle parameter 2.4) Close the Rockey4ND dongle (RY_CLOSE) Objective: To close a Rockey4ND dongle with a specific handle. Input parameters: function = RY_CLOSE Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. 2.5) Read the Rockey4ND dongle (RY_READ) Objective: To read the contents of the User Data Zone (UDZ). Input parameters: function = RY_READ Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the contents of the UDZ written to the memory buffer.
Objective: To write data to the User Data Zone. (UDZ) Input parameters: function = RY_WRITE Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. 2.7) Generate a Random Number (RY_RANDOM) Objective: To get a random number from the dongle. Input parameters: function = RY_RANDOM Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the *p1,*p2,*p3,*p4 address populated with the random number. 2.8) Generate Seed Code Return Values (RY_SEED) Objective: To get return codes from the input of a seed code. Input parameters: function = RY_SEED Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the following addresses populated with seed code return values: *p1 = Return Code 1 2.9) Write the User ID [*] (RY_WRITE_USERID) Objective: To write the user defined “User ID” to the User ID Zone (UIZ). Input parameters: function = RY_WRITE_USERID Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. 2.10) Read User ID (RY_READ_USERID) Objective: To read the user defined “User ID” from the User ID Zone (UIZ). Input parameters: function = RY_READ_USERID Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the *lp1 address populated with the User ID. 2.11) Set a Rockey4ND Module [*] (RY_SET_MOUDLE) Objective: To write a value to a specific Rockey4ND module and set the Decrement attribute. Input parameters: function = RY_SET_MOUDLE Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in module unit # “*p1” storing value “*p2” and the Decrement attribute set to “0” or “1”. 2.12) Check a Rockey4ND Module (RY_CHECK_MOUDLE) Objective: To read the attributes of a specific Rockey4ND module. Input parameters: function = RY_CHECK_MOUDLE Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in “*p2” populated in the value from the Zero Value attribute (1 = module value is not zero), and “*p3” populated with the value from the Decrement attribute (1 = module can be decreased). 2.13) Write Arithmetic [*] (RY_WRITE_ARITHMETIC) Objective: To write user-defined mathematical instructions to the User Algorithm Zone (UAZ). Input parameters: function = RY_WRITE_ARITHMETIC Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the UAZ populated with the algorithm command string from the buffer. 2.14)Calculate 1 (RY_CALCULATE1) Objective: To return the results of a calculation performed in Rockey4ND, using input provided by the developer and the RY_CALCULATE1 function. Input parameters: function = RY_CALCULATE1 Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the addresses p1, p2, p3 and p4 populated with the results of the calculation. 2.15) Calculate 2 (RY_CALCULATE2) Objective: To return the results of a calculation performed in Rockey4ND, using input provided by the developer and the RY_CALCULATE2 function. Input parameters: function = RY_CALCULATE2 Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the addresses p1, p2, p3 and p4 populated with the results of the calculation. 2.16) Calculate 3 (RY_CALCULATE3) Objective: To return results of a calculation performed in Rockey4ND, using input provided by the developer and the RY_CALCULATE3 function. Input parameters: function = RY_CALCULATE3 Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the addresses p1, p2, p3 and p4 populated with the results of the calculation. 2.17)Decrease Module Unit (RY_DECREASE) Objective: To decrease the value in a specified Rockey4ND module by “1”. Input parameters: function = RY_DECREASE Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will reduce the value stored in module *p1 by “1”. 3.Return Codes
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Copyright (C) 2007-2009 Feitian Technologies Co.,Ltd.
All rights reserved. |