Although DLL only allows exporting plain “C” functions, object-oriented methodology is employed during the interface design. All functions operate on a special object called the barcode object. The object is identified by a 32-bit interger type called HANDLE. A HANDLE is defined as a void* pointer in C language, and a Long in classic Visual Basic.

A typical application creates the barcode object through function CreateBarcodeObject and retrieves the handle to the object. Subsequently it calls various functions to manipulate the object properties. The function mbxExportImage is used to retrieve the barcode image renderings. After the application finishes using the object, it calls the function DestroyBarcodeObject to release all resources allocted to the object.

A barcode object is created through function CreateBarcodeObject, which has the following prototype:

HANDLE CreateBarcodeObject(const char* lpszLicenseTo, 
                                 const char* lpszRegCode);

The CreateBarcodeObject function creates a barcode object using default properties and returns a number that uniquely identifies the object (handle). Through the handle, the client application modifies the object properties, persists the object to a disk file, and retrieves barcode rendering in a variety of image formats.

Two string parameters are required for the function. At the time when you place the order, we assign the LicenseTo and Registration code to you when the order is completed. You should keep the registration code in a safe place and use them only in the source code. Putting the registration code visible to your user, such as a plain text file, is not allowed.

The function will always succeed unless the program does not have sufficient memory. Therefore the return value does not tell you if the license paratmeters are correct. Instead the object enters the DEMO mode. Under the demo mode, the barcode image exported has a “DEMO” watermark.

The application can query if the barcode object is under the demo mode by calling function IsBarcodeObjectDemo. If the function returns a non-zero value, the barcode object is under demo mode and every barcode image exported carries a “DEMO” watermark.

There are several dozen properties you can modify on the barcode object. Most properties are not related to each other; so changing one won't affect others. However, several exceptions exist. Changing the Symbology property will also cause the Message property to change due to the fact that different symbologies have different default Message values. Changing the measurment unit (Measurement property) will cause values of length properties to change so that the barcode sizes remain intact.

To access a specific property your application calls get_XXX and put_XXX functions. Here XXX is the property name. For example, to retrieve the vlaue of the Message property, use get_Message function. To set the Message property, use put_Message function. For a list of all properties, refer to Chapter 8, Barcode Object Properties and Methods Reference.

Properties of a barcode object can be saved into a file and loaded at later time. The functions mbxLoad and mbxSave are used for loading and saving the barcode object, respectively. The first parameter is the file path, and the second parameter indicates the file type.

The client application calls ExportImage or ExportImage2 functions to export the barcode image to a disk file or a Stream object.

After you have done with the object, you should call DestoryBarcodeObject to destroy the barcode object. By doing so you release all resources associated with the object.

Not all functions succeed unconditionally. You should always check the return value for errors when working with the program.

Barcode DLL reports two kinds of errors - operational errors and encoding errors. They are handled in different ways.

Operational errors occur when an operation fails or a property is set to an invalid value. The error is reported as returned value of the function. The error value is expressed in a 32-bit integer form, very similiar to the HRESULT error code in the COM world. Consequently you can use SUCCEEDED and FAILED macros to tell if the operation succeeds or fails.

For a list of applicable error codes, refer to the Chapter 9, Error Handling.

When error happens, you can use GetLastBarcodeErrorMessage to retrieve the reason, as demonstrated by the VB code below:

Dim rc As Long
rc=put_Message(handle, "ABCD123")
If ( rc < 0 ) Then
    GetLastBarcodeErrorMessage(barcode_object_handle, strError)
    MsgBox strError
End IF

The DLL is thread safe - all functions can be called simutaneousely from multiple threads. However, the same barcocde object handle value should only called by a single thread at any time. If you need to do so, serialize the access using the protection mechanism provided by the operating system.

When working with our DLL interface, pay attention to the boolean type and the string type used by exported functions. See below for details.

char message[1024];
get_Message(handle, message);

Dim strDefaultValue As String * 1024
Dim rc As Long
rc = get_Message(barcode_object_handle, 
         strDefaultValue)

.Net programming has gained popularity recently. To use DLL in a .net program, you need to declare functions using DllImportfirst. We have included a .Net sample called CaseCodePrintwith the product. We wrapped all DLL export functions within a C# class. To make our code easy to understand, we wrap these functions into properties and methods. You may take a look at our sample for details.