Configure Visual C++ 10 Projects to Build Functions

Contents

Method 1: Copy Sample Project Files
Method 2: New or Existing Project
Deploying Custom C++ Functions

To build 64-bit StreamBase C++ functions for Windows, you must use Visual C++ 10.0 (Visual Studio .NET 2010), and must configure your Visual C++ projects as described on this page.

Alternate Project Types

To build C++ clients for Windows using Visual C++ 10.0, configure your projects as described in Configure Visual C++ 10 or 11 Projects to Build Clients.

StreamBase does not provide a Debug version of the library files for StreamBase Server, and thus does not support building Debug versions of DLLs that contain custom functions. The instructions on this page describe the configuration to build a Release version of your DLLs. If you need to debug your function's code, you must arrange to do so independent of the StreamBase framework.

StreamBase supports only 64-bit custom C++ native-code functions on Windows. Support for building 32-bit C++ functions was removed due to library changes that accompanied that release. See Building Custom C++ Functions on Windows for suggestions for migrating any 32-bit C++ functions you may have written for older StreamBase releases.

To configure Visual C++ 10.0 projects to build custom C++ functions, you can either:

  • Method 1: Copy the project files from the StreamBase custom-simple-function sample and edit them.

  • Method 2: Create a new project from scratch or modify an existing Visual Studio project.

Method 1: Copy Sample Project Files

  1. Copy the streambase-install-dir\sample\custom-simple-function folder to your Visual C++ workspace. For clarity, keep your Visual C++ workspace in a separate location from your StreamBase Studio workspace.

    Note

    You must copy this folder from the StreamBase installation directory. Do not make a copy of the custom-simple-function sample in your StreamBase Studio workspace, because the Studio workspace sample does not have the Visual Studio .sln and .vcproj files.

    If you are creating a custom aggregate function, copy the following folder instead: streambase-install-dir\sample\custom-aggregate-function

  2. Locate the custom-simple-function.sln file. You can optionally rename this file before opening it the first time. Preserve the .sln extension, and choose a basename that reflects the purpose of the intended client. For example, rename custom-simple-function.sln to wicked-cool-function.sln.

  3. Use Windows Explorer to make a copy of LogFunction.cpp and rename it as appropriate for your project (such as wicked-cool-function.cpp).

  4. Start Visual C++ 10.0. Use File → Open → Project to load custom-simple-function.sln (or your renamed solution file, wicked-cool-function.sln).

  5. Rename the logfunction project in the Solution Explorer as appropriate for your custom function. For example, rename it to wicked-cool.

  6. Add the copy of the source file you renamed in step 3 to your project and remove the original LogFunction.cpp.

  7. Right-click your project in the Solution Explorer and select Properties from the context menu.

  8. In the Linker properties, optionally rename the DLL file to be generated from log.dll to the filename of your choice, such as wickedcool.dll:

    On the Configuration drop-down menu, select the Release configuration.

    Make sure the following setting is in place:

    Property Folder Property Page Property Row Setting
    Linker General Output File $(OutDir)\my-dll-name.dll

  9. Locate the places in the project properties that use ${STREAMBASE_HOME} and replace those with the absolute path to your top-level StreamBase installation directory. In general, do this by clicking in the specified setting row, then click the button with three dots to open the Additional Directories dialog. Select a row in this dialog and use the second three-dot button to navigate to your StreamBase installation's directory.

    1. On the Configuration drop-down menu, select All Configurations.

      Make sure the following setting is in place:

      Property Folder Property Page Property Row Setting
      C/C++ General Additional Include Directories Replace the path that uses ${STREAMBASE_HOME} with the absolute path to the include directory of your StreamBase installation: streambase-install-dir\include

    2. On the Configuration drop-down menu, select the Release configuration.

      Make sure the following setting is in place:

      Property Folder Property Page Property Row Setting
      Linker General Additional Library Directories Replace the path that uses ${STREAMBASE_HOME} with the absolute path to the lib\$(Platform)\$(PlatformToolset) directory of your StreamBase installation: streambase-install-dir\lib\$(Platform)\$(PlatformToolset)

  10. Set the Solution Configuration to Release and build your project. Verify that a DLL of the specified name is generated in the Release folder.

  11. Begin customizing the source file for your client.

  12. When you have a DLL ready to test in the context of a StreamBase application, follow the steps in Deploying Custom C++ Functions.

Method 2: New or Existing Project

Whether using an existing Visual C++ project or starting with a new one, make sure the project's settings match those described in the following steps. All project settings not listed here are optional, and can be changed to match the requirements of your project.

  1. In Visual C++ Studio, select File → New → Project.

    1. In the New Project dialog, select Visual C++ Projects → Win32, then select Win32 Project.

    2. In the Name field, enter a name for your project.

    3. In the Win32 Application Wizard dialog, select Application Settings.

    4. Under Application Type, select DLL.

    5. If you already have a C++ file that contains your function, then under Additional options, select Empty project. If you are starting from scratch, leave this check box cleared.

    6. Click Finish. If you have a project already open, click Yes to close that project and open your new project.

  2. If you already have a C++ file for your function, use Windows Explorer to drag that file to the newly created project folder.

  3. Back in Visual C++ Studio, in the Solution Explorer panel, right-click the project just created and select Properties from the context menu.

  4. On the Configuration drop-down menu, select All Configurations.

    Make sure the following settings are in place:

    Property Folder Property Page Property Row Setting
    General — Configuration Type From the drop-down menu, select Dynamic Library (.dll).
    General — Use of MFC From the drop-down menu, select Use Standard Windows Libraries.
    General — Use Managed Extensions No
    C/C++ General Additional Include Directories Path to the include directory of your StreamBase installation.

    streambase-install-dir\include

    Do not use the environment variable STREAMBASE_HOME to define this path (unless you have applied this variable globally as described in StreamBase Command Prompt). If there is already an entry in this row that uses ${STREAMBASE_HOME}, replace that entry.

    Instead, click in the row and use the button with three dots on the right side to open the Additional Include Directories dialog. Select a row in this dialog and use the second three-dot button to navigate to your StreamBase installation's include directory.

    C/C++ Preprocessor Preprocessor Definitions Append the following definition to the default list:

    STREAMBASE_PTHREAD_DLL

    C/C++ Precompiled Headers Create/Use Precompiled Headers From the drop-down menu, select Not Using Precompiled Headers.

  5. On the Configuration drop-down menu, select the Release configuration.

    Make sure the following settings are in place:

    Property Folder Property Page Property Row Setting
    C/C++ Code Generation Runtime Library From the drop-down menu, select Multi-threaded DLL (/MD).
    Linker General Additional Library Directories Append the following path to the entries in that row:

    streambase-install-dir\lib\$(Platform)\$(PlatformToolset)

    As described above, do not use STREAMBASE_HOME to define this path. If there is already an entry in this row that uses ${STREAMBASE_HOME}, replace that entry.

    Click in the row and use the button with three dots on the right side to open the Additional Library Directories dialog. Select a row in this dialog and use the second three-dot button to navigate to your StreamBase installation's lib\$(Platform)\$(PlatformToolset) subdirectory.

Now customize the source file for your function, then build the containing DLL. When are ready to test your function's DLL in the context of a StreamBase application, follow the steps in the next section.

Deploying Custom C++ Functions

To deploy your custom functions in the context of your StreamBase application, follow these steps:

  1. Copy the DLL file generated in the steps above to the root of your StreamBase Studio project folder.

  2. Edit your server configuration file to reference the new function:

    1. Reference the DLL file name in <plugin> child element of the <global> element. For example: 

      <global>
  <plugin file="./wicked-cool.dll" />
</global>

      See the <global> section of the StreamBase Server Configuration File XML Reference for details.

    2. Declare the function in a <custom-function> element as described in the <custom-functions> section of the StreamBase Server Configuration File XML Reference.

  3. Make sure you have referenced your custom function's name with consistent spelling and capitalization in the following places. The following examples show the usage for a fictional function named coolfunc:

    • The required C++ macro in the C++ file that defines your function. For example: 

      STREAMBASE_DEFINE_PLUGIN_FUNCTION(LogFunction, "coolfunc");

    • The <custom-function> element of the server configuration file. For example: 

      <custom-function name="coolfunc" type="simple" >
  <args>
  ...

    • In the expression in an EventFlow or StreamSQL module that calls your function. For example: 

      callcpp("coolfunc", 1, 3)

Your DLL can contain multiple custom functions, following these rules:

  • Add multiple C++ files to the Visual C++ project that generates the same DLL, with one function per C++ file.

  • For each function defined in the DLL, provide a separate <custom-function> element in the server configuration file.