The API

An introduction to SDK functions, their purposes, and parameters.

The functions available in the C/C++ SDK to register a query are listed below:

• C8Status C8RegisterQuery (const C8Char * i_server_uri, const C8Char *i_workspace, const C8Char *i_query_name, const C8Char *i_query_text, C8SizeType i_stream_cnt, const C8StreamInfo ** i_streams, C8SizeType i_parameter_cnt, const C8ParameterInfo **i_parameters, const C8CompilerOptions *i_opts, C8Bool i_cleanup_tmp_files, C8Char *** o_tmp_file_list); – Purpose: Register a query.

  Parameters:

  • i_server_uri: The URL of the (for example, http://localhost:6789) that manages the query.

  • i_workspace: The name of the workspace where the query is run.

  • i_query_name: The name of the query. This name must be unique among the dynamically loaded queries for this workspace.

  • i_query_text: The text of the query. The text of the query is a set of zero or more CCL statements. Any CCL constructs may be used in the query.

  • i_stream_cnt: The number of streams in the query.

  • i_streams: An array of objects describing the streams used by the query.

  • i_parameter_cnt: The number of parameters in the query.

  • i_parameters: An array describing the query parameters. If you are not specifying any parameters (for example, "$XYZ" in a CCL statement), you can pass NULL.

  • i_opts: A struct describing the compiler options to be set. Pass NULL to use defaults.

  • i_cleanup_tmp_files: A boolean indicating whether to clean up temporary files.

  • o_tmp_file_list: A pointer that will be set to point to an array of character strings that contain the names of the temporary files. If you do not want the names of these files, simply pass NULL.

    Note: this is a pointer to a pointer to a pointer (3 asterisks) since it's a pointer to an array of arrays of characters. If a non-null pointer to a C8Char ** is passed, the location is filled with a newly allocated, NULL-terminated array of NULL-terminated strings. Note that the array may be filled (and therefore will need to be freed) even if the function does not return success.

  Returns: C8_OK on success; C8_FAIL otherwise.

• C8StreamInfo * C8StreamInfoCreateInputBound(const C8Char * i_name, const C8Char * i_src_uri, C8Interval i_max_delay, C8Bool i_is_out_of_order, C8Interval i_out_of_order_delay, C8Bool i_is_use_server_timestamp); – Purpose: Creates an instance of C8StreamInfo describing a bound input stream.

  Parameters:

  • i_name: The stream name as used in the CCL query text.

  • i_src_uri: The URI of the stream this stream binds to.

  • i_max_delay: Max delay parameter for the input stream, in microseconds.

  • i_is_out_of_order: C8_TRUE if the stream is to accept out-of-order messages; C8_FALSE otherwise.

  • i_out_of_order_delay: If out-of-order messages are accepted, the maximum out-of-order delay, in microseconds.

  • i_is_use_server_timestamp: C8_TRUE if the stream is to set the timestamp of incoming messages to the current server time; C8_FALSE otherwise.

  Returns: An instance of the C8StreamInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8StreamInfoDestroy().

• C8StreamInfo * C8StreamInfoCreateInputUnbound(const C8Char * i_name, const C8Schema * i_schema, C8Interval i_max_delay, C8Bool i_is_out_of_order, C8Interval i_out_of_order_delay, C8Bool i_is_use_server_timestamp); – Purpose: Creates an instance of C8StreamInfo describing an unbound input stream.

  Parameters:

  • i_name stream: The name as used in the CCL query text.

  • i_schema: The stream schema.

  • i_max_delay: Max delay parameter for the input stream, in microseconds.

  • i_is_out_of_order: C8_TRUE if the stream is to accept out-of-order messages; C8_FALSE otherwise.

  • i_out_of_order_delay: If out-of-order messages are accepted, the maximum out-of-order delay, in microseconds.

  • i_is_use_server_timestamp: C8_TRUE if the stream is to set the timestamp of incoming messages to the current server time.

  Returns: An instance of C8StreamInfo if successful; NULL otherwise

• C8StreamInfo * C8StreamInfoCreateOutputUnbound( const C8Char * i_name, const C8Schema * i_schema); – Purpose: Creates an instance of C8StreamInfo describing an unbound output stream.

  Parameters:

  • i_name: The stream name as used in the CCL query text.

  • i_schema: The stream schema.

  Returns: An instance of the C8StreamInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8StreamInfoDestroy().

• C8StreamInfo * C8StreamInfoCreateOutputBound( const C8Char * i_name, const C8Char * i_dst_uri); – Purpose: Creates an instance of C8StreamInfo describing a bound output stream.

  Parameters:

  • i_name: The stream name as used in the CCL query text.

  • i_dst_uri: The URI of the stream this stream binds to.

  Returns: An instance of the C8StreamInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8StreamInfoDestroy().

• C8StreamInfo * C8StreamInfoCreateLocal(const C8Char * i_name); – Purpose: Creates an instance of C8StreamInfo describing a local stream.

  Parameters:

  • i_name: The stream name as used in the CCL query text.

  Returns: An instance of the C8StreamInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8StreamInfoDestroy().

• void C8StreamInfoDestroy(C8StreamInfo * i_stream_info); – Purpose: Deallocates a C8StreamInfo object.

  Parameters:

  • i_stream_info: The object to destroy.

• C8ParameterInfo * C8ParameterInfoCreateInteger (const C8Char * i_name, C8Int i_value); – Purpose: Creates an instance of a C8ParameterInfo describing an integer query parameter.

  Parameters:

  • i_name: The parameter name.

  • i_value: The parameter value.

  Returns: An instance of the C8ParameterInfo if successful; NULL otherwise.

• C8ParameterInfo * C8ParameterInfoCreateFloat (const C8Char * i_name, C8Float i_value); – Purpose: Creates an instance of a C8ParameterInfo describing a query parameter of type float.

  Parameters:

  • i_name: The parameter name.

  • i_value: The parameter value.

  Returns: An instance of the C8ParameterInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8ParameterInfoDestroy().

• C8ParameterInfo * C8ParameterInfoCreateString (const C8Char * i_name, const C8Char * i_value); – Purpose: Creates an instance of a C8ParameterInfo describing a query parameter of type string.

  Parameters:

  • i_name: The parameter name.

  • i_value: The parameter value.

  Returns: Instance of the C8ParameterInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8ParameterInfoDestroy().

• C8ParameterInfo * C8ParameterInfoCreateBoolean (const C8Char * i_name, C8Bool i_value); – Purpose: Creates an instance of a C8ParameterInfo describing a query parameter of type boolean.

  Parameters:

  • i_name: The parameter name.

  • i_value: The parameter value.

  Returns: An instance of the C8ParameterInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8ParameterInfoDestroy().

• C8ParameterInfo * C8ParameterInfoCreateLong (const C8Char * i_name, C8Long i_value); – Purpose: Creates an instance of a C8ParameterInfo describing a query parameter of type long.

  Parameters:

  • i_name: The parameter name.

  • i_value: The parameter value.

  Returns: An instance of the C8ParameterInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8ParameterInfoDestroy().

• C8ParameterInfo * C8ParameterInfoCreateTimestamp (const C8Char * i_name, C8Timestamp i_value); – Purpose: Creates an instance of a C8ParameterInfo describing a query parameter of type timestamp.

  Parameters:

  • i_name: The parameter name.

  • i_value: The parameter value.

  Returns: An instance of the C8ParameterInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8ParameterInfoDestroy().

• C8ParameterInfo * C8ParameterInfoCreateInterval (const C8Char * i_name, C8Interval i_value); – Purpose: Creates an instance of a C8ParameterInfo describing a query parameter of the type timestamp.

  Parameters:

  • i_name: The parameter name.

  • i_value: The parameter value.

  Returns: An instance of the C8ParameterInfo if successful; NULL otherwise. The object returned by this function must be deallocated with C8ParameterInfoDestroy().

• void C8ParameterInfoDestroy (C8ParameterInfo * i_prm_info); – Purpose: Deallocates a C8ParameterInfo object.

  Parameters:

  • i_prm_info: The C8ParameterInfo object to destroy.