SoftwareShield ClientProtector COM Component > Linking To ClientProtector™ In Your Application

Linking To ClientProtector™ In Your Application

The ClientProtector is a COM server dll. This means that you must link dynamically to the component.

To link to the SSCProt.dll, your application installer must distribute the dll along with your application and license and any other supporting files your license may need. For more information about deployment, refer to: Deploying the License for Your Application.

Aside from deployment, your applications installer program must register the SSCProt.dll with the Windows system. Check your installers documentation for information on how to do this. As with all COM servers, you can manually register or un-register the dll with the Windows system using the command line utility "regsvr32.exe".

Once registered, you are ready to use the ClientProtector in your application. The first step is always to create an instance of the component in memory by creating an object from the interface you choose to use.

Your application must do this immediately upon starting and before trying to use it - just like any other COM server or ActiveX component. Depending on your environment, there are numerous ways to do this. Sometimes this process is handled for you. For example, in Delphi, you can simply import the component using "Project > Import Type Library" then finding "SoftwareShield ClientProtector" in the list of registered servers and clicking "Install". This creates a component wrapper that you can actually drop right on your form and use directly. In other environments, you may have to do more memory management, but the basic principle is the same:

  1. Ensure the SSCProt.dll is registered on your system. When you installed the SoftwareShield SDK it was registered on your development machine. You will need to have your applications installer register it on your customers system also.
  2. Reference the SSCProtector component in your development environment the way you normally would reference any other COM server dll component.
  3. Declare (and instantiate) an instance of the SSCProtector component.
  4. Connect an event sink (if necessary) to the IDispatch interface of the component to receive events.
  5. Use the component.
  6. Un-initialize or free memory when you are done.

The previous steps are intentionally general because different environments and the way you choose to import or use the COM server have different implementations of how to (most easily) manage the COM object, its memory and interface pointers.

One important condition you must be prepared for in your code when linking to the ClientProtector is an "EOLEException". This exception is thrown when a COM server class is not registered or is not in the location specified or a number of other conditions that prevent it from being created. If your function calls to the ClientProtector throw this exception it is best to warn the user and shut down the application. Otherwise, a cracker could defeat your license simply by un-registering the ClientProtector.

Pass-By-Reference Strings and Memory Management

This section on memory management of strings may not apply to you. Note that many IDEs manage this aspect of the memory for you and you do not explicitly have to allocate or de-allocate the memory. For example, VB6 and C#.NET you do not have to worry about it because the built in garbage collection will reclaim the memory automatically. However, in MSVC++ and Borland C++ Builder, you should always observe the below guidelines. Check your compilers documentation and the MSDN pages listed below for more information about this.

In all COM servers you should be sure that you are managing memory for strings correctly.  In particular:

  1. You may need to explicitly free the memory for any strings which are pass-by-reference from the ClientProtector (have the IDL attribute of [out]) when you are finished with them.  You can do this with a call to the Windows API function SysFreeString.

  2. You may need to explicitly allocate memory for any strings which are passed from your application to the ClientProtector in an event handler.  In almost every case this is immediately handled for you when you initialize the string in your application, but in some cases, you may need to do this with the Windows API function SysAllocString.  This is  especially true in event handlers since the memory created on the stack for a local string variable may be reclaimed when the event handler returns even though the ClientProtector is not finished with the value in the string yet.

The best-practices approach the ClientProtector uses (advocated by Microsoft) for string parameters that cross the COM server boundary is that the COM server (the ClientProtector) allocates any required memory for pass-by-reference strings internally (using the Windows system API SysAllocString()).  The "caller" of the function (your software) needs to do two things for these pass by reference strings:

  1. Pass an empty string pointer parameter to be used by the server which is initially set to NULL or at least empty.

  2. When the call completes and you are done with the string, de-allocate any memory for it using the Windows system API call SysFreeString().

There are other general guidelines, but these are the most important ones. For more information about these guidelines see: Microsoft - Memory Management Rules.  In particular, the guideline says: "Out-parameter—Must be allocated by the one called; freed by the caller using the standard COM task memory allocator..."

For specific step-by-step instructions on how to import and link to the ClientProtector COM server from your application, see the following:

The following sections give step-by-step specific examples of how you can use the ClientProtector from Microsoft C#.NET, Microsoft Visual Basic, Microsoft Visual C++, Borland Delphi and Borland C++ Builder.

Related Topics