Creating a Conversion DLL

The conversion DLL has to be a native Win32 DLL (no .NET assembly). To create it in Microsoft Visual Studio, you have to create a Win32 project and select the application type DLL.

On 64-bit operating systems, Silk Performer uses a 64-bit process to analyze capture files and generate scripts. Thus, you have to build two versions of the conversion DLL: a 32-bit DLL, which is used for replaying scripts, and a 64-bit DLL, which is used for generating scripts. The 64-bit DLL has to be named <name of the 32-bit DLL>_x64.dll and located in the same directory as the 32-bit DLL.

If you cannot create a 64-bit DLL for any reason, you can force Silk Performer to use a 32-bit process for script generation by setting the following registry key to 1: HKEY_LOCAL_MACHINE\SOFTWARE\Silk\SilkPerformer\<version>\Force32BitCaptureAnalyzer.

Attention: Using the 32-bit script generator can cause issues with large capture files.

Silk Performer has provided sample Microsoft Visual Studio projects with header and .cpp files that give you guidance on how to create your own custom conversion DLL. The samples are located at <public user documents>\Silk Performer <version>\SampleApps\SampleConversion.

After you have created the project, there are some additional project settings to change:

The Character Set option has to be set to Use Multi-Byte Character Set (MBCS). This is a requirement, because the strings to be converted are passed as MBCS strings.
It is recommended that you use the static version of the C-runtime to remove dependencies to C-runtime DLLs. These dependencies could cause problems if the C-runtime DLLs (of used version) are not installed on the agent or controller machine. To use the static C-runtime libraries, change the Runtime Library setting in C++ / Code Generation to the following:
- Multi-threaded (/MT) in the Release configuration
- Multi-threaded Debug (/MTd) in the Debug configuration

Recommendation

If you reference the conversion DLL in a recording rule, you have to copy the DLL either into the Silk Performer recording rules directory or into the project directory. When developing the conversion DLL in Microsoft Visual Studio, you could copy the DLL to one of these directories (recording rules or project) in a post-build step or change the output directory path in the Release configuration to the recording rules directory.

Exporting the conversion function

You must export the conversion function with the following signature:

extern "C"
{
  __declspec( dllexport )
  long MyConversionFunction(
  LPCSTR sOriginalValue,
  LPSTR sConvertedValue,
  unsigned long* psConvertedValueLen,
  void* pReserved);
}

The purpose of using C linkage (extern "C") is to turn off C++ name mangling of the exported function. If using C++ linkage, other information like the types of arguments would be put into the exported name of the function. Use the "pure" function name as the exported function name (this is MyConversionFunction in the example above).

Function arguments:

sOriginalValue	The MBCS string value that has to be converted.
sConvertedValue	The string buffer that receives the converted value as MBCS string.
psConvertedValueLen	Points to a variable which contains the length of the string buffer sConvertedValue. This variable’s value has to be set to the number of bytes written to sConvertedValue if the conversion succeeded. This variable value has to be set to the number of bytes required for the converted value if the size of the string buffer sConvertedValue is too small.
pReserved	Reserved for future usage.
Return value	ERROR_SUCCESS (0): Returned if the conversion was successful. psConvertedValueLen now contains the number of bytes written to sConvertedValue. ERROR_INSUFFICIENT_BUFFER (122): Returned if the conversion failed because the size of of sConvertedValue (psConvertedValueLen) is too small for the converted value. psConvertedValueLen now contains the number of bytes required to store the converted value. The function will be called again with size of sConvertedValue increased to psConvertedValueLen. Return any other value to indicate that the conversion failed.