GameShield COM-Activator™ Component  > Linking to the GameShield COM Activator™

Linking to the GameShield COM-Activator™ in your Applications

The COM Activator is (as its name suggests) a COM server dll. This means that you must link dynamically to the component.

Only use the COM Activator if you wish build your own user interface for generating Activation Codes.

You do this by linking to the COM server dll (SSCGen.dll) and calling functions on its exposed interface.  Keep in mind that generating Activation Codes can more easily be accomplished using the Manual-Activator or the Web-Activator. The COM-Activator however is the best way to programmatically generate Activation Codes.

Never distribute the COM Activator to clients as part of your software. It is strictly for your own internal use as another way to generate Activation Codes.

To link to the SSCGen.dll, your application installer must simply create the SSCodeGenerator object inside it just like any other COM server or ActiveX component.

The SSCGen.dll is registered with the Windows system when you installed the GameShield DRM Kit. However, if you are building your own UI for distribution internally (inside your own organization) you will need to register the SSCGen.dll with Windows when your host application gets installed.  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 COM Activator 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 "GameShield COM Activator" 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 SSCGen.dll is registered on your system. When you installed the GameShield DRM Kit it was registered on your development machine. You will need to have your applications installer register it on any other systems which require it also.
  2. Reference the SSCodeGenerator 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 SSCodeGenerator component.
  4. Use the component.
  5. 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 COM Activator 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.

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 COM Activator (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.

The best-practices approach the COM Activator uses (advocated by Microsoft) for string parameters that cross the COM server boundary is that the COM server (the SSCodeGenerator) 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&emdash;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 COM Activator server from your application, simply follow the same guidelines for linking to the ClientProtector - the process is identical except for the name of the server and component:

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.

Note: The COM Activator only comes with the Enterprise, Internet and Server Editions of the GameShield DRM Kit.