Get the C client libraries for Linux :

https://download.diffusiondata.com/clients/6.11.2/c/diffusion-c-6.11.2.zip

Get the C client libraries for Windows :

https://download.diffusiondata.com/clients/6.11.2/c/diffusion-c-windows-6.11.2.zip

Get the C client libraries for OS X/macOS:

https://download.diffusiondata.com/clients/6.11.2/c/diffusion-c-osx-6.11.2.zip

Capabilities

To see the full list of capabilities supported by the C API, see Feature support in the Diffusion API.

Support

If you require libraries compiled on a different platform, this can be provided as an additional service by our Consulting Services team. Contact [email protected] to discuss your requirements.

Resources

Using

On Linux

The C libraries are provided compiled for 64-bit Linux in the file diffusion-c-version.zip. A dynamic library, libdiffusion.so, and a static library, libdiffusion.a, are available.

To use the C API on Linux ensure that the following dependencies are available on your development system:

• Perl Compatible Regular Expressions (PCRE) library, version 8.3 or later

  For more information, see http://pcre.org

• zLib library, version 1.2 or later

  For more information, see http://www.zlib.net

You can download these dependencies through your operating system's package manager.

The C client library statically links to Apache Portable Runtime (APR) version 1.6.1 with APR-util. Ensure that you set APR_DECLARE_STATIC and APU_DECLARE_STATIC before you use any APR includes. You can set these values in the following ways:

• By including diffusion.h before any APR includes. The diffusion.h file sets these values.
• As command-line flags.

For more information, see http://apr.apache.org

On Windows

The C library is provided as a static library compiled for 32-bit and 64-bit Windows in the file diffusion-c-windows-version.zip. This static library, uci.lib, is compiled with Visual C Compiler 2015 (version 140), which is shipped by default with Microsoft^® Visual Studio 2015. You must use this version of Visual C Compiler or later and use Windows 7 or later. Earlier versions are not supported.

Other Windows compilers, such as Clang and GCC, are not supported.

When compiling with Visual C Compiler 2015, define /D WIN32 in the compiler settings.

To use the C API on Windows ensure that the following dependencies are available on your development system:

• Perl Compatible Regular Expressions (PCRE) library, version 8.3 or later

  For more information, see http://pcre.org

• zLib library, version 1.2 or later

  For more information, see http://www.zlib.net

We provide these dependencies in the diffusion-c-windows-version.zip file.

The C client library statically links to APR version 1.6.1 with APR-util. Ensure that you set APR_DECLARE_STATIC and APU_DECLARE_STATIC before you use any APR includes. You can set these values in the following ways:

• By including diffusion.h before any APR includes. The diffusion.h file sets these values.
• As command-line flags.

For more information, see http://apr.apache.org

On OS X/macOS

The C library is provided as a static library, libdiffusion.a, compiled for 64-bit OS X/macOS in the file diffusion-c-osx-version.zip.

To use the C API on OS X/macOS ensure that the following dependencies are available on your development system:

• Perl Compatible Regular Expressions (PCRE) library, version 8.3 or later

  For more information, see http://pcre.org

• zLib library, version 1.2 or later

  For more information, see http://www.zlib.net

You can download this dependencies using brew.

The C client library statically links to APR version 1.6.1 with APR-util. Ensure that you set APR_DECLARE_STATIC and APU_DECLARE_STATIC before you use any APR includes. You can set these values in the following ways:

• By including diffusion.h before any APR includes. The diffusion.h file sets these values.
• As command-line flags.

For more information, see http://apr.apache.org

For building using GCC, use Xcode 7.1 or later, which includes Apple^® LLVM.

Defining the structure of record topic data using XML

Data on record topics can be structured using metadata. Other Diffusion™ Cloud APIs provide builder methods you can use to define the metadata structure. The C API uses XML to define the structure of a record topic's metadata.

The following schema describes the structure of that XML :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="field" type="field"/>

  <xs:element name="message" type="message"/>

  <xs:element name="record" type="record"/>

  <xs:complexType name="record">
    <xs:complexContent>
      <xs:extension base="node">
        <xs:sequence>
          <xs:choice minOccurs="0" maxOccurs="unbounded">
            <xs:element ref="record"/>
            <xs:element ref="field"/>
          </xs:choice>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="node">
    <xs:sequence/>
    <xs:attribute name="name" type="xs:string" use="required"/>
    <xs:attribute name="multiplicity" type="xs:string"/>
  </xs:complexType>

  <xs:complexType name="field">
    <xs:complexContent>
      <xs:extension base="node">
        <xs:sequence/>
        <xs:attribute name="type" type="dataType" use="required"/>
        <xs:attribute name="default" type="xs:string"/>
        <xs:attribute name="scale" type="xs:integer"/>
        <xs:attribute name="allowsEmpty" type="xs:boolean"/>
        <xs:attribute name="customFieldHandlerClassName" type="xs:string"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="message">
    <xs:complexContent>
      <xs:extension base="record">
        <xs:sequence/>
        <xs:attribute name="topicDataType" type="topicDataType"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:simpleType name="dataType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="integerString"/>
      <xs:enumeration value="string"/>
      <xs:enumeration value="customString"/>
      <xs:enumeration value="decimalString"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="topicDataType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="record"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Threading model

The C API is not thread-safe. Session and their derived artifacts must belong to a single thread or only be acted upon by a single thread at any time.

Internally, the C client creates threads for managing the connection to Diffusion Cloud . All callbacks into user-defined code are synchronous and it usually the case that these must execute as quickly as possible. If this code runs for a non-trivial amount of time, ensure that it hands off work to your own threads.

It is safe to send messages while processing callbacks, as outbound messages are queued and are sent as soon as possible.

Ensure that callbacks do not alter the session as this can lead to undefined behavior. This includes calling functions such as session_close() from the session state change callback.

Always call session_close() and session_free() from the same thread that created the session with session_create() or session_create_async(). This allows the threads to be joined and reaped correctly, and is a requirement of the APR library which the C API relies on.

Regular expressions

The C client uses a different regular expression engine to Diffusion Cloud . Some regular expressions in topic selectors are evaluated on the client and others on Diffusion Cloud . It is possible that topic selectors that include complex or advanced regular expressions can behave differently on the client and on Diffusion Cloud .

For more information, see Regular expressions.