Note: This article describes how to capture user registration data; go here to learn how to find and manage user registration data in your Zentitle dashboard.
Introduction
Zentitle allows you to collect and register various forms of data against a user record in the NLS system, this is typically information such as name and address, or e-commerce order data or perhaps maintenance and version information, but it can be whatever you wish to associate to a ComputerID/Unique PC in our system. So this is data per a "machine ID" rather than a license code. This data can be added over time and a historical record is kept of any data recorded against the unique machine.Implementation
In order to capture data into Zentitle you need to code your own Application to send the data to use in the form outlined below and in the example code projects listed at the base of this article.
This "registration" data can be different for any client and any time of collection, i.e. the data structure is not fixed and can be variable for different clients and for different times of capture. The registration information collected is displayed on the server side for a specific computer ID.
The server will show historical records and the date of capture for each computer ID. This enables the user to see how the client side data has changed over time. The data passed to the server will take the form of XML tags and can be varied for each end-user and collection, for example:
<clientinfo><firstname>Joe</firstname><lastname>Bloggs</lastname><field1>field1data</field1></clientinfo>
There is no restriction on the field names except for they must be XML friendly. As such, they cannot contain white spaces. Also, the XML elements in <clientinfo> must not (a) have child elements or (b) be repeated (e.g. <a>val1</a><a>val2</a>.)
The following fields are treated as "special recommended fields" and show on the server side at the top of the data shown and will be searchable (case-sensitive)
- firstname
- lastname
- company
The example applications provided illustrate how to collect and send the end user consumer data.
The registration data fields present in the example application are given for illustration purposes. Some or all of these may be excluded by removing the associated form components (labels and textboxes) and associated code from the btn_Save_Click event handler and CreateRegistrationFile method described above. Additional fields may be created by duplicating the code in these methods corresponding to the provided fields and tailoring it (providing corresponding form component/field names) to suit.
It should be noted, however, that four of the fields provided in the example application, ‘firstname’, ‘lastname’, ‘company’ and ‘email’, are tagged and so are searchable on the Zentitle server. As such, retention of some or all of these fields is recommended.
Sample projects code below can be used for your specific IDE, please choose the one that is most suited for your usage, if you don't see what you need simply contact us at https://support.nalpeiron.com
We are assuming that you will add calls to your own program code to capture what you wish, below are examples of what you could simply add to your own projects to start getting User data into Zentitle.
Example Code for C/C++
In C/C++ the NSLObtainLicense function is used get a new license or update you current license.Its prototype is:
int NSLObtainLicense(const char * authentication, int32_t * licenseStatus, const char * xmlRegInfo, const char * specialID)
During the initial or any subsequent call to NSLObtainLicense information may be passed to the Zentitle server for later retrieval using the xmlRegInfo string. This string may consist of any valid UTF-8 characters. The string will be parsed as XML on the Zentitle server so if any XML reserved characters are used (<, >, &, ', and ") they should be used to form valid XML. If you do not wish to send any information to Nalpeiron the xmlRegInfo pointer may be set to NULL.
A call to NSLObtainLicense that includes data to be sent to Zentitle would look something like this:
char * licenseNo="1234567890"; int * licenseStatus; char * xmlRegInfo="<clientinfo><firstname>Joe</firstname><lastname>Bloggs</lastname><field1>field1data</field1></clientinfo>";
specialID *= "0"; ret = NSLObtainLicense(licenseNo, &licenseStatus, xmlRegInfo, specialID);
Example Code for Java
The Zentitle licensing library is accessed in Java via a JNI wrapper.To get a new license or update the current license for your product you would call the NSLObtainLicensefunction which is easily accessed via the callNSLObtainLicense method.
callNSLObtainLicense is a member of the NSL class.
The method's signature is:
int callNSLObtainLicense(String licenseNo, String xmlRegInfo, specialID);
During the initial or any subsequent call to callNSLObtainLicense information may be passed to the Zentitle server for later retrieval using the xmlRegInfo string. This string may consist of any valid UTF-8 characters. The string will be parsed as XML on the Zentitle server so if any XML reserved characters are used (<, >, &, ', and ") they should be used to form valid XML. If you do not wish to send any information to Zentitle the xmlRegInfo pointer may be set to NULL.
A call to NSLObtainLicense that includes data to be sent to Zentitle would look like this:
int i;
NALP nalp = new NALP();
NSL nsl = new NSL(nalp, 0);
i = nsl.callNSLObtainLicense("1234567890", "<clientinfo><firstname>Joe</firstname><lastname>Bloggs</lastname><field1>field1data</field1></clientinfo>","0");
Example Code for C#
The RegistrationForm class
The right-most item on the menu strip of the example application has the nameregisterationToolStripMenuItem and text ‘Registration’.On selecting the single menu item registerUserToolStripMenuItem (with text ‘Register User’) an instance of the RegistrationForm class is instantiated where the user is invited to enter registration information upon which this is stored in the Zentitle database.
The code for this class, to be referenced below, is contained in the file RegistrationForm.cs.
A new registration form is instantiated by the event-handler:
RegisterUserToolStripMenuItem_Click
On being fired, this event immediately disables the registerUserToolStripMenuItem in order to prevent multiple RegistrationForm instances being created.
Two delegates are passed as parameters to the new RegistrationForm instance RegForm: G_Del and R_Del, being instances of the delegate classes GetLicenceFromServerDelegate and ReactivateRegistrationDelegate respectively. The latter reactivates theregisterUserToolStripMenuItem component on closure of RegistrationForm while the former obtains the licence number (see below.)
For the NSLExample application, these delegate classes are defined in the file NSLExample.cs and belong, along with all other components of this example application, to the NSLExample namespace. In the ShaferExample application, the filename and namespace are ShaferExample.cs and ShaferExample respectively.
The RegistrationForm is a simple WinForm with 5 textboxes (and associated labels) together with a ‘Save’ button (btn_Save.) The names of the textboxes and their associated labels are shown in the table below (with the meaning of the associated user data to be entered in each textbox being self-explanatory).
| Textbox | Label |
|---|---|
| tb_FirstName | lbl_FirstName |
| tb_LastName | lbl_LastName |
| tb_Company | lbl_Company |
| tb_Telephone | lbl_Telephone |
| tb_Email | lbl_Email |
In addition to the standard initialization code, the RegistrationForm constructor initializes two local delegatesGLFS_Delegate and RR_Delegate which are identified with those passed in, having local names mDel andrDel respectively.
The user enters data into the textboxes which is processed upon btn_Save being clicked, triggering the event handler for its click event, as described next.
The btn_Save_Click event
The handler for this event performs a number of tasks in the following order:Declarations/initializations:
| valid_data | validation flag initialized as true. |
|---|---|
| ReturnValue | licence number initialized as 0. |
| RegistrationFile | XML document used to save registration data. |
Data capture/validation.
The validation flag valid_data is calculated as the logical AND the return values of:
!string.IsNullOrWhiteSpace(this.tb_FirstName.Text)
and the text entered into the other textboxes in the RegistrationForm, i.e. it takes the value true if all of these text boxes are populated and false otherwise.
3If valid data, the CreateRegistrationFile() method is called (see below) which populatesRegistrationFile with corresponding XML registration data.
This file is then saved as RegFile.xml in the application’s working folder. Finally, GLFS_Delegate is called which populates ReturnValue with the licence number (See ‘Obtaining the Licence Number’ below.) If data is not valid, a MessageBox displays the error message "Invalid input data"
4 RR_Delegate() is then called, which re-enables registerUserToolStripMenuItem on the application main form, so that subsequent user registrations may take place.
The RegistrationForm is then closed.
Obtaining the Licence Number
The call to obtain the consumer licence number is initiated within the btn_Save_Click event handler at the line
ReturnValue = GLFS_Delegate();
The delegate GLFS_Delegate() is an instance of the class GetLicenceFromServerDelegate which calls the method
public int GetLicenseFromServer()
of the NSLExample class. The int return value of this method is the LicenseStatus, which will be 0 on success and have an error code value otherwise. The pertinent functionality here of this method is that it reads the registration data file RegFile.xml into the string RegData which is then, along with the licence code obtained from
private String GetLicenseCode()
passed on to
public int GetLicense(string LicenseCode, string RegistrationData)
This method accepts null values for the RegistrationData string and a null should be passed in the event that RegFile.xml is not present.
The CreateRegistrationFile() method
This method performs the following tasks:
1Creates local XmlDocument doc.
2Creates the root element <clientinfo> for this XmlDocument.
3Creates the remaining elements which are child elements of <clientinfo>.
These elements contain the registration data captured from the textboxes in RegForm. For each such textbox, e.g. tb_FirstName, the following processing takes place:
- XmlElement firstname = doc.CreateElement("firstname");
- Here, the XmlElement <firstname> is created
- firstname.InnerText = HttpUtility.HtmlEncode(tb_FirstName.Text)
The value of the <firstname> element is set as the text captured from tb_FirstName textbox encoded into HTML. The reason for this encoding is to permit the use, in field values, of characters prohibited in XML and to ensure that they are correctly displayed on a web page.
The field names must conform to XML standards. In particular, they may not include white spacing. If spacing is required in a field name, a similar effect may be achieved using the underscore character ‘_’, which is permissible.
- root.AppendChild(firstname);
- The <firstname> element is appended to doc as a child of the root element <clientinfo>.
- The XmlDocument doc is returned to the RegistrationForm.
The RegistrationForm class
The right-most item on the menu strip of the example application has the nameregisterationToolStripMenuItem and text ‘Registration’.On selecting the single menu item registerUserToolStripMenuItem (with text ‘Register User’) an instance of the RegistrationForm class is instantiated where the user is invited to enter registration information upon which this is stored in the Zentitle database.
The code for this class, to be referenced below, is contained in the file RegistrationForm.vb.
A new registration form is instantiated by the event-handler:
RegisterUserToolStripMenuItem_Click
On being fired, this event immediately disables the registerUserToolStripMenuItem in order to prevent multiple RegistrationForm instances being created.
Two delegates are passed as parameters to the new RegistrationForm instance RegForm: G_Del and R_Del, being instances of the delegate classes GetLicenceFromServerDelegate and ReactivateRegistrationDelegate respectively. The latter reactivates theregisterUserToolStripMenuItem component on closure of RegistrationForm while the former obtains the licence number (see below.)
For the NSLExample application, these delegate classes are defined in the file NSLExample.vb and belong, along with all other components of this example application, to the NSLExampleVB namespace. In the ShaferExample application, the filename and namespace are ShaferExample.vb and ShaferExampleVB respectively.
The RegistrationForm is a simple WinForm with 5 textboxes (and associated labels) together with a ‘Save’ button (btn_Save.) The names of the textboxes and their associated labels are shown in the table below (with the meaning of the associated user data to be entered in each textbox being self-explanatory).
| Textbox | Label |
|---|---|
| tb_FirstName | lbl_FirstName |
| tb_LastName | lbl_LastName |
| tb_Company | lbl_Company |
| tb_Telephone | lbl_Telephone |
| tb_Email | lbl_Email |
In addition to the standard initialization code, the RegistrationForm constructor initializes two local delegatesGLFS_Delegate and RR_Delegate which are identified with those passed in, having local names mDel and rDel respectively.
The user enters data into the textboxes which is processed upon btn_Save being clicked, triggering the event handler for its click event, as described next.
The btn_Save_Click event
The handler for this event performs a number of tasks in the following order:1Declarations/initializations:
- valid_data – validation flag initialized as true.
- ReturnValue – licence number initialized as 0.
- RegistrationFile – XML document used to save registration data.2
Data capture/validation.
The validation flag valid_data is calculated as the logical AND the return values of:Not String.IsNullOrWhiteSpace(Me.tb_FirstName.Text)
and the text entered into the other textboxes in the RegistrationForm, i.e. it takes the value true if all of these textboxes are populated and false otherwise.
3If valid data, the CreateRegistrationFile() method is called (see below) which populatesRegistrationFile with corresponding XML registration data.
This file is then saved as RegFile.xml in the application’s working folder. Finally, GLFS_Delegate is called which populates ReturnValue with the licence number (See ‘Obtaining the Licence Number’ below.) If data is not valid, a MessageBox displays the error message "Invalid input data"
4 RR_Delegate() is then called, which re-enables registerUserToolStripMenuItem on the application main form, so that subsequent user registrations may take place.
The RegistrationForm is then closed.
Obtaining the Licence Number
The call to obtain the consumer licence number is initiated within the btn_Save_Click event handler at the line
ReturnValue = GLFS_Delegate()
The delegate GLFS_Delegate() is an instance of the class GetLicenceFromServerDelegate which calls the method
Private Function GetLicenseFromServer() As Integer
of the NSLExample class. The Integer return value of this method is the LicenseStatus, which will be 0 on success and have an error code value otherwise. The pertinent functionality here of this method is that it reads the registration data file RegFile.xml into the string RegData which is then, along with the licence code obtained from
Private Function GetLicenseCode() As [String]
passed on to
Public Function GetLicense(LicenseCode As String, RegistrationData As String) As Integer
This method accepts null values for the RegistrationData string and a Nothing should be passed in the event that RegFile.xml is not present.
The CreateRegistrationFile() method
This method performs the following tasks:
1Creates local XmlDocument doc.
2Creates the root element <clientinfo> for this XmlDocument.
3Creates the remaining elements which are child elements of <clientinfo>.
These elements contain the registration data captured from the textboxes in RegForm. For each such textbox, e.g. tb_FirstName, the following processing takes place:
- Dim firstname As XmlElement = doc.CreateElement("firstname")
- Here, the XmlElement <firstname> is created
- firstname.InnerText = HttpUtility.HtmlEncode(tb_FirstName.Text)
The value of the <firstname> element is set as the text captured from tb_FirstName textbox encoded into HTML. The reason for this encoding is to permit the use, in field values, of characters prohibited in XML and to ensure that they are correctly displayed on a web page.
The field names must conform to XML standards. In particular, they may not include white spacing. If spacing is required in a field name, a similar effect may be achieved using the underscore character ‘_’, which is permissible.
- root.AppendChild(firstname)
- The <firstname> element is appended to doc as a child of the root element <clientinfo>.
- The XmlDocument doc is returned to the RegistrationForm.