C/C++ API Reference

The Fabasoft app.telemetry Software-Telemetry C/C++ API allows you to instrument any C/C++ application with instrumentation points to see what's going on in complex applications.

Constants(C/C++)

This chapter lists the available constants to be used for instrumenting your C/C++ application.

Flags (C/C++)

Flags are used to specify the type of an event and are passed as argument to every event call. They are predefined by the API with the data type UInt8 and have the following possible values:

• APM_FLAG_NONE
• APM_FLAG_ENTER
• APM_FLAG_LEAVE
• APM_FLAG_WAIT
• APM_FLAG_WARNING
• APM_FLAG_ERROR
• APM_FLAG_PROCESS_INFO

For more details about the flags and there meaning see the general chapter “Flags”.

Log Level (C/C++)

An event will only be logged if the event-level is lower or equal to the value selected in the session or log-definition. The log levels are predefined by the API with the data type UInt8 and have the following possible values:

• APM_EVENT_LEVEL_LOG
• APM_EVENT_LEVEL_IPC (only internal)
• APM_EVENT_LEVEL_NORMAL
• APM_EVENT_LEVEL_DETAIL
• APM_EVENT_LEVEL_DEBUG

For more details about the log levels and there meaning see the general chapter “Log Level”.

Parameter Types (C/C++)

Parameter types provide type information of parameters in a call to APMEventArgs (see “Method APMEventArgs (C/C++)”)

Predefined Modules (C/C++)

For a list of available standard modules with a set of predefined events see chapter “Standard Modules”.

Predefined Events (C/C++)

The SDK already provides a set of predefined events used for general purpose. For a full listing of all available predefined events see the generic chapter "Predefined Events".

Error/Trace Events:

Use these standard events to mark error, warning or info conditions in your application like in the following example:

• APM_EVENT_ERROR
• APM_EVENT_WARNING
• APM_EVENT_INFO
• APM_EVENT_TRACE

Predefined Application Property Keys and Names (C/C++)

Predefined Application Value Keys and Names (C/C++)

Counter Attributes (C/C++)

Counter attributes define behavior, aggregation, measurement, representation and labels of registered counters. Some of the attributes can be changed but most must be defined during the initial counter registration.

Remarks:

The two attributes APM_COUNTER_ATTRIBUTE_WARNING_LIMIT and APM_COUNTER_ATTRIBUTE_ERROR_LIMIT are available with Version 2021 UR 1. Use them to automatically configure a corresponding service check with „warning“ and „error“ property as given, like in the following examples:

Counter Types (C/C++)

Counter Datatypes (C/C++)

Aggregation Function Names (C/C++)

Data types (C/C++)

APMApplicationHandle (C/C++)

APMApplicationHandle is used to identify an application registered in your process by calling APMRegisterApplication (see “Method APMRegisterApplication (C/C++)”). The handle is only valid in the same process until you call APMUnregisterApplication (see “Method APMUnregisterApplication (C/C++)”)

APMModuleHandle (C/C++)

APMModuleHandle is used to identify a module registered in your process by calling APMRegisterModule (see “Method APMRegisterModule (C/C++)”). The handle is valid only in the same process until you call APMUnregisterModule (see “Method APMUnregisterModule (C/C++)”).

APMCounterHandle (C/C++)

APMCounterHandle is used to identify a counter or counter instance registered using APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”).

APMCounterAttributeType (C/C++)

APMCounterAttributeType is used to identify which attribute is described by the encompassing APMCounterAttribute structure. See “Counter Attributes (C/C++)” for valid values.

APMCounterType (C/C++)

APMCounterType specifies the type of the counter registered using APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”). See 2.1.9 "Counter Types (C/C++)" for a list of valid values.

APMCounterDataType (C/C++)

APMCounterDataType specifies the data-type of the counter registered using APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”). See “Counter Datatypes (C/C++)” for a list of valid values.

APMCounterAttribute (C/C++)

APMCounterAttribute is used to pass attributes to the registration function APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”).

APMCounterCallback (C/C++)

APMCounterCallback is used to pass a counter callback with optional custom data to the APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”) function via the attributes as an APM_COUNTER_ATTRIBUTE_CALLBACK.

APMEventId (C/C++)

APMEventId is used to identify an event. The event id must be unique per module and you are free to choose a value. Avoid using predefined event ids (see Predefined Events (C/C++)).

APMEventId is declared as:

APMEventLevel (C/C++)

APMEventLevel is used to specify the importance of an event.

Possible values are:

• APM_EVENT_LEVEL_LOG
• APM_EVENT_LEVEL_IPC
• APM_EVENT_LEVEL_NORMAL
• APM_EVENT_LEVEL_DETAIL
• APM_EVENT_LEVEL_DEBUG

APMEventFlags (C/C++)

APMEventFlags is used to specify the type of an event.

Possible values are:

• APM_FLAG_NONE
• APM_FLAG_ENTER
• APM_FLAG_LEAVE
• APM_FLAG_WAIT
• APM_FLAG_WARNING
• APM_FLAG_ERROR

APMParameterType (C/C++)

APMParameterType is used to specify the type of the parameter (see “Method APMEventArgs (C/C++)”).

Possible values are:

• APM_PARAMETERTYPE_INT32
• APM_PARAMETERTYPE_INT64
• APM_PARAMETERTYPE_STRING

EnumAppFilterValuesCallback (C/C++)

Applications may register a callback when calling APMRegisterApplication (see Method APMRegisterApplication (C/C++)”). The callback should enumerate all valid filter values by repeatedly calling APMRegisterFilterValue (see “Method APMRegisterFilterValue (C/C++)”) to register all valid values, that may be selected when starting a Software-Telemetry session. The callback will be triggered by the app.telemetry server, if no filter values are defined for the registered application or once per hour to refresh the values.

APMContext (C/C++)

Values of type APMContext need to be passed during inter-process communication to provide the caller context to the invoked program (see “Method APMGetContext (C/C++)” and “Method APMAttachContext (C/C++)”).

APMSyncMark (C/C++)

Values of type APMSyncMark need to be passed during inter-process communication to provide time sequence information (see “Method APMGetSyncMark (C/C++)” and “Method APMSetSyncMark (C/C++)”).

APMParamHandle (C/C++)

Pointers of type APMParamHandle are used to register multiple parameters for use with APMEventParam (see “Method APMEventParam (C/C++)” and “Parameter Functions (C/C++)”).

Registration Functions (C/C++)

Method APMRegisterApplication (C/C++)

Call this function once to provide information about the context of the application.

Parameters:

• appName: The name of your application (utf-8 encoded)
• appId: The Id of your application (utf-8 encoded)
• appTierName: The tier inside the application (utf-8 encoded)
• appTierId: Id to distinguish multiple services of one application tier (utf-8 encoded)
• filterCallback: A callback for filter registration

Return Value:

• This function returns the application handle of the registered application.

Remarks:

Your application must be registered before any events can be fired.

Method APMRegisterApplicationProperty (C/C++)

Call APMRegisterApplicationProperty to register additional application registration properties immediately after you call to APMRegisterApplication to ensure proper operation.

Parameters:

• application: The handle of the application for which you are registering additional registration properties.
• propertyKey: The application defined key of the property or the predefined APM_APP_PROPERTY_INSTANCE_GUID_KEY (utf-8 encoded). Limited to 256 Bytes. Keys starting with “apm:” are reserved for internal use.
• propertyName: The display name of the property (utf-8 encoded) (APM_APP_PROPERTY_INSTANCE_GUID_NAME for the example above). Limited to 512 Bytes.
• propertyValue: The value of the property (utf-8 encoded). Limited to 32768 Bytes.

Return Value:

This function does not return any value.

Remarks:

Application registration properties cannot be changed after they have been set.

Method APMRegisterApplicationValue (C/C++)

Call APMRegisterApplicationValue to register additional static information about your application such as the version number or the display name of this globally unique instance.

Parameters:

• application: The handle of the application for which you are registering additional registration properties.
• valueKey: The application defined key of the value or one of the predefined (APM_APP_VALUE_VERSION_KEY, APM_APP_VALUE_INSTANCE_NAME_KEY, …) (utf-8 encoded). Limited to 256 Bytes. Keys starting with “apm:” are reserved for internal use.
• valueName: The display name of the property (utf-8 encoded) (APM_APP_VALUE_VERSION_NAME, APM_APP_VALUE_INSTANCE_NAME_NAME,… for the examples above). Limited to 512 Bytes.
• value: The value of the property (utf-8 encoded). Limited to 32768 Bytes.

Return Value:

This function does not return any value.

Remarks:

Application values may be changed at runtime but must not have a high change frequency and do not have any history of previous values.

Method APMUnregisterApplication (C/C++)

Call APMUnregisterApplication at the end of your program to tell app.telemetry agent that your program lifetime ends now.

Parameters:

• application: The handle of the application which gets unregistered.

Return Value:

This function does not return any value.

Remarks:

Unregistering all applications will stop the connection to the app.telemetry agent. As reconnecting takes time it is not recommended to unregister and reregister applications frequently.

Method APMRegisterModule (C/C++)

Call this function to register modules inside your application.

Parameters:

• modulename Desired name of the APMModule (utf-8 encoded).

Return Value:

• This function returns a handle which you need to associate events to their corresponding module.

Remarks:

• Different modules are shown as different bars during the analysis.
• Modules are registered per process and not per application, so each application in a process can use modules registered one in that process.
• Modules are identified by their name. A registration of a module with a previously registered module name will return the same module handle as the first module registration as long as the module has not been unregistered.

Method APMUnregisterModule (C/C++)

Call APMUnregisterModule if you do not need to trace any more events tied with this module. Calling this function will clean up several internal processes.

Parameters:

• module: Handle to the module which should get unregistered

Return Value:

This function does not return any value.

Remarks:

You may register and unregister modules any time but you should not reregister a single module frequently as the app.telemetry server has to keep all module registrations to be able to display all requests of a process correctly.

Method APMModuleRegisterEvent (C/C++)

It is required and important to register the events used in your application in order to get the correct event names and parameter descriptions as provided. The APMModuleRegisterEvent-function will tell the app.telemetry server a name for every event-ID and optionally parameter descriptions for the parameters used in the event calls.

Parameters:

• module: Module handle for which you register the event.
• eventid: This is the id of the event you want to register.
• description: The description of the event.
• parameterdescription: Name of event parameters. If more parameters are used in one event, separate the parameter names by semi-colon (;). For example: "name;count;size"

Return Value:

This function does not return any value.

Remarks:

If an event has more than one parameter you need to separate the parameterdescription with semicolons (;).

Method APMRegisterFilterValue (C/C++)

It is useful to register all possible filter values used in your application in order to get a list of available filters with descriptions in the client interface.

You may actively register filter values any time after registering the application by calling the APMRegisterFilterValue method.

To optimize filter registration in case enumeration of filter values is a costly action, the registration of filter values may be performed in the EnumAppFilterValuesCallback function, which is only called if needed (see “EnumAppFilterValuesCallback (C/C++)”).

Parameters:

• app: The Handle of the APMApplication representing this application.
• value: value is the raw filter value.
• description: This is the description which is presented in the Client-User-Interface as filter.

Return Value:

This function does not return any value.

Remarks:

This function may be called inside the EnumAppFilterValuesCallback function which is initiated by the app.telemetry server.

Method APMRegisterCounter (C/C++)

Call APMRegisterCounter once for every counter or counter instance to make the counter known to the app.telemetry library for collection.

Parameters:

• utf8GroupName: The group name of the counter (utf-8 encoded) Note: Group names starting with “apm” are reserved for internal use and must not be used by application developers.
• utf8CounterName: The name of the counter (utf-8 encoded).
• counterType: The counter type, see Counter Types (C/C++)
• counterDataType: The counter data type, see Counter Datatypes (C/C++).
• dataAddress: The address from which the counter value can be read the number of bytes fetched depends on the datatype of the counter.
• counterAttributes: List of APMCounterAttribute structures with an end marker (APM_COUNTER_ATTRIBUTE_NONE) that define additional counter attributes, see Counter Attributes (C/C++) for a list of supported attributes.
• Return Value:
• This function returns the handle to the counter that can be used to change some attributes and unregister the counter.

Method APMUpdateCounterAttributes (C/C++)

Call APMUpdateCounterAttributes to update some attributes of a registered counter. Note: Only the listed attributes can be updated using this function.

Parameters:

• counterHandle: The handle of a registered counter whose attributes need to be updated.
• counterAttributes: List of APMCounterAttribute structures with an end marker (APM_COUNTER_ATTRIBUTE_NONE) that define attributes to be updated.

Supported Attributes:

• APM_COUNTER_ATTRIBUTE_GROUP_DISPLAY_NAME
• APM_COUNTER_ATTRIBUTE_DISPLAY_NAME
• APM_COUNTER_ATTRIBUTE_INSTANCE_DISPLAY_NAME

Return Value:

This function does not return any value.

Method APMUnregisterCounter (C/C++)

Call APMUnregisterCounter to unregister a previously registered counter to free it’s associated resources and stop any collection.

Parameters:

• counterHandle: The handle of a registered counter that will be unregistered.
• Return Value:
• This function does not return any value.

Context Handling Functions (C/C++)

Method APMCreateContext (C/C++)

Call APMCreateContext to create a new Software-Telemetry context. If the filter value matches a currently started session filter, logging is started for the current execution thread. Make sure to call APMReleaseContext when exiting the context. A context can be regarded as a complete request that is traced through several involved threads or modules. And the full context request has a duration that spans the interval from CreateContext to ReleaseContext.

Parameters:

• app: The Handle of the APMApplication representing this application.
• filtervalue: (optional) This value is used to match a filter of a started Software-Telemetry session. You should register filter values used by calling APMRegisterFilterValue (see “Method APMRegisterFilterValue (C/C++)”)

Return Value:

This function does not return any value.

Method APMAttachContext (C/C++)

Call APMAttachContext to restore the context acquired through APMGetContext in another thread or process (see “Passing Context” and “Method APMGetContext (C/C++)”).

Parameters:

• app: The Handle of the APMApplication representing this application.
• context: The context which you want to attach to.

Return Value:

This function does not return any value.

Method APMGetContext (C/C++)

Call the APMGetContext-method to get a new context handle.

This context handle is used to synchronize different threads/processes/modules - this helps you track the control flow through a distributed environment. The acquired context handle has to be submitted (either by transmitting over the network or in another way) to the thread/process being called which associates the calling thread with itself by passing the context to the APMAttachContext-method.

Parameters:

• context: APMGetContext creates a context at the location pointed to by context.

Return Value:

• If the function succeeds, the return value is 1 and a context has been saved to the location which context pointed to.
• If no context has been created, the return value is 0.

Method APMGetSyncMark (C/C++)

Call the APMGetSyncMark-method to get a synchronization handle that can be passed to another thread/process/module to synchronize control flow.

The difference between a sync mark and a context is:

• A context is used to associate with one request. It is created by the initiator and attached to by other threads/process belonging to the same request.
• A sync mark is only a time synchronization handle between the different threads/processes which can be used several times to synchronize the control flow exactly (different systems may have different timestamps and different time precision).

Parameters:

• context: APMGetSyncMark creates a sync mark at the location pointed to by context.

Return Value:

• If the function succeeds, the return value is 1 and a sync mark has been saved to the location which context pointed to.
• If no sync-mark has been created, the return value is 0.

Method APMSetSyncMark (C/C++)

Call APMSetSyncMark to pass a sync mark you got from APMGetSyncMark for synchronizing the sequence of events (see “Synchronizing Timeline with SyncMarks” and “Method APMGetSyncMark (C/C++)”).

Parameters:

• context: The sync mark which you want to sync with.

Return Value:

This function does not return any value.

Method APMReleaseContext (C/C++)

Call APMReleaseContext to finish logging and to flush logged information to the app.telemetry infrastructure.
Make sure to call APMReleaseContext when exiting the context (when the request is finished).

Parameters:

This function does not take any arguments.

Return Value:

This function does not return any value.

Remarks:

• If you don't call APMReleaseContext the request keeps the running status until the request-timeout has been reached.

Method APMDetachThread (C/C++)

Call the APMDetachThread-method when processing of a particular request is suspended and will be resumed later in this or another thread in the same process. Pass the handle returned by this method to the APMAttachThread-method to resume processing.

This functionality is in particular useful in queuing systems, where a large number of requests will be queued and processed by a small number of worker threads asynchronous to the initial request. Using the APMDetach-/APMAttachThread methods you can follow the request through the process and even measure the time spent in the queue, even if a different thread continues processing.

Parameters:

• handle: APMDetachThread generates an id (64bit) that uniquely identifies the current state of the request.

Return Value:

• If the function succeeds, the return value is 1 and a context has been saved to the location which context pointed to.
• The function will return 0 in case the library is not available or if no request has been started using APMCreateContext and/or APMAttachContext.

Remarks:

Be careful to use APMDetachThread and APMAttachThread in a balanced way. APMDetachThread will store the current state of the request in memory and APMAttachThread will remove the information from memory while restoring the request state. So calls to APMDetachThread lacking a continuation will leak memory and will leave the request in a "running" state. Multiple calls to APMAttachThread with the same handle will not have an effect, because the request state is only available to the first call to APMAttachThread.

Method APMAttachThread (C/C++)

Call the APMAttachThread-method when processing of a particular request is resumed after being suspended in this or another thread of the same process. Pass the handle returned by APMDetachThread-method to restore the recorded state of the request.

This functionality is in particular useful in queuing systems, where a large number of requests will be queued and processed by a small number of worker threads asynchronous to the initial request. Using the Detach-/AttachThread methods you can follow the request through the process and even measure the time spent in the queue, even if a different thread continues processing.

Parameters:

• handle: APMAttachThread uses the handle generated by APMDetachThread to identify the current state of the request.

Remarks:

See “Method APMDetachThread (C/C++)”

Event Functions (C/C++)

The four APMEvent… functions log Software-Telemetry data. They have the first 4 parameters in common and vary in the options to pass additional parameters.

The common parameters are:

• module: The handle to a previously registered module (see “Method APMRegisterModule (C/C++)”).
• eventid: Id of the event you which you set (see “Method APMModuleRegisterEvent (C/C++)”).
• level: The log-level for which this event should be logged (see “APMEventLevel (C/C++)”).
• flags: Use the flags parameter to specify the type of an event (see “APMEventFlags (C/C++)”).

Method APMEvent (C/C++)

Call the APMEvent function to log an event without parameters. Only the event-ID and the flags define the representation of the event that will be displayed with the registered event name for the used id.

Parameters:

• The APMEvent function has only the four base parameters (see “Event Functions (C/C++)”).

Return Value:

This function does not return any value.

Method APMEventArgs (C/C++)

Use APMEventArgs to log an event with various parameters, which must be passed in a predefined format.

Parameters:

• The APMEventArgs function has the four base parameters (see “Event Functions (C/C++)”).
• paramCount: The number of parameters you want to pass to this function.
• paramTypes: This is an array containing the types of the parameters. The size of the array is equal to paramCount.
• paramValues: This pointer points to the continuous memory region containing the parameters.
• paramValueSize: This is the size of the memory region containing the parameter values (paramValues).

Return Value:

This function does not return any value.

Method APMEventParam (C/C++)

Call the APMEventParam-method to log events with a generic parameter structure - with any number and combination of textual (string) values and integer values (32- and 64-bit).
To use the APMEventParam-method you have to initialize an APMParamHandle. With a few helper methods you can add values to this parameter object (see “Parameter Functions (C/C++)”) and use the parameter object in the event function to be logged. Do not forget to free the parameter handle with APMParamFree (see “Method APMParamFree (C/C++)”).

Parameters:

• The APMEventParam function has the four base parameters (see “Event Functions (C/C++)”).
• param: This is the handle you obtained from a call to APMParamInit.

Return Value:

This function does not return any value.

Method APMEventStr (C/C++)

Use APMEventStr to log an event with an additional string value as parameter.

Parameters:

• The APMEventStr function has the four base parameters (see “Event Functions (C/C++)”).
• param: Pointer to null-terminated, utf8-encoded string. The maximum string length allowed is 32768 Byte.

Return Value:

This function does not return any value.

Parameter Functions (C/C++)

The parameter functions provide a way to pass up to 255 parameters to an APMEventParam call.

Allocate an APMParamHandle by calling APMParamInit. Add parameters calling APMParamAdd32, APMParamAdd64 or APMParamAddString. Pass the APMParamHandle to the APMEventParam function and finally call APMParamFree to free associated memory.

Method APMParamInit (C/C++)

APMParamInit is used to initialize an APMParamHandle.

Parameters:

This function does not take any arguments.

Return Value:

• This function returns a handle which you can use to add parameters and pass to APMEventParam.

Remarks:

• Do not forget to call APMParamFree (see “Method APMParamFree (C/C++)”) to release internal memory.

Method APMParamAdd32 (C/C++)

Call APMParamAdd32 to add a 32 bit unsigned integer to the parameter handle.

Parameters:

• param: APMParamHandle obtained from APMParamInit.
• value: The value which you want to add.

Return Value:

This function does not return any value.

Method APMParamAdd64 (C/C++)

Call APMParamAdd64 to add a 64 bit unsigned integer to the parameter handle.

Parameters:

• param: APMParamHandle obtained from APMParamInit.
• value: The value which you want to add.

Return Value:

This function does not return any value.

Method APMParamAddString (C/C++)

Call APMParamAddString to add a string to the parameter handle.

Parameters:

• param: APMParamHandle obtained from APMParamInit.
• value: The value which you want to add. The maximum length of the utf-8 encoded string is 32768 Byte.

Return Value:

This function does not return any value.

Method APMParamFree (C/C++)

Call APMParamFree to release the memory allocated for the parameters created by APMParamInit.

Parameters:

• param: APMParamHandle created by APMParamInit.

Return Value:

This function does not return any value.

Remarks:

Use this function to free internal memory associated to the parameters.

Fabasoft app.telemetry Button (C/C++)

Method APMReport (C/C++)

Call APMReport to create a new feedback report.

The filter value will be matched to the description using the registered filter values. Use the textual description of the feedback entered by the user or generated by the application to identify the report session later again.

If a log pool exists for the current application, the latest requests where the APMCreateContext filtervalue parameter matches the filtervalue passed to the APMReport function, will be associated with the feedback.

Parameters:

• app: The Handle of the APMApplication representing this application.
• filtervalue: filtervalue to match requests with.
• reportkey: A key value may be generated by the calling application to associate further descriptions to a feedback. If empty, a new feedback report will be generated on each call and no further information may be attached to the feedback.
• description: Textual description of the feedback entered by the user or generated by the application. The maximum length of the description is 32768 Bytes.

Return Value:

This function does not return any value.

Remarks:

• Since version 2009 Fall Release (4.3) the key value is used to associate further descriptions to a feedback.
• In previous versions each call of this function had generated a new feedback report.

Method APMReportValue (C/C++)

Call APMReportValue to add a key/value pair to an existing report.

Parameters:

• app: The Handle of the APMApplication representing this application.
• reportkey: reportkey matches the reportkey of the APMReport function to associate the value with the report session.
• key: A key describes the meaning of the value. Only one value can be associated to a single key in one report session.
• value: Text (max. 32 kBytes).

Return Value:

This function does not return any value.

Method APMReportContent (C/C++)

Call APMReportContent to associate content with an existing report.

Parameters:

• app: The Handle of the APMApplication representing this application.
• reportkey: reportkey matches the reportkey of the APMReport function to associate the content with the report session.
• filename: A filename describing the content of the file. (max. 256 Bytes)
• data: Pointer to a binary data.
• size: Size of the data content.

Return Value:

• This function does not return any value.

Method APMReportFile (C/C++)

Call APMReportFile to associate a file with an existing report.

Parameters:

• app: The handle of the APMApplication representing this application.
• reportkey: reportkey matches the reportkey of the APMReport function to associate the value with the report session.
• filename: A filename describing the content of the file. (max. 256 Bytes)
• filehandle: File pointer that has been opened for reading.

Return Value:

This function does not return any value.

Remarks:

• Until version 2010 Spring Release the filehandle has been declared as HANDLE under Microsoft Windows. This has been changed to a FILE pointer for consistency and dependency reasons since version 2010 Summer Release.

Status Functions (C/C++)

Method APMHasActiveContext (C/C++)

Call APMHasActiveContext to test if a software-telemetry session is active for some logging level. This information should be used to avoid costly operations preparing parameters for events that are currently not logged.

Parameters:

• level: The event level of the event you prepare parameters for.

Return Value:

• The return value is non-zero if the event will be logged.

Method APMIsConnected (C/C++)

Call APMIsConnected to test, if the application has successfully registered to an app.telemetry agent.

Parameters:

This function does not take any arguments.

Return Value:

• If the application is not connected to an app.telemetry agent this function returns zero.
• If the function is successfully connected, the return value is one.

Method APMIsCompatible (C/C++)

Call APMIsCompatible to test, if the application was linked with a version that is compatible with the dynamically loaded library.

Parameters:

• size: Size in Bytes of the memory region where the second parameter points. Allocate at least 200 Bytes to get the full version message.
• message: Pointer to a memory region of the size specified in the first parameter. A descriptive text with an optional product name and version number will be stored in the allocated memory region.

Return Value:

• This function returns non-zero if the used versions are compatible.

Explicit Transaction Functions (C/C++)

The functions specified so far all are executed within the context of the current thread. In some cases, it is necessary to explicitly define the current transaction context to the context handling functions, for example if your application's processes aren't based on operating system threads.

To use the explicit transaction functions, you have to define the symbolic constant APM_EXPLICIT_TRANSACTION in a preprocessor directive for your application. If only APM_EXPLICIT_TRANSACTION is defined, only the explicit transaction functions can be used. You have to define APM_THREAD_TRANSACTION in addition if you want to use the usual thread context functions from above.

Method APMTxCreateContext (C/C++)

Call APMTxCreateContext to create a new Software-Telemetry context analogously to APMCreateContext. You use the APMTransactionHandle returned by this function to pass to other explicit transaction functions for the definition of the current transaction context. You have to call APMTxReleaseContext with the returned transaction handle when exiting the context.

Parameters:

• tx: Set this value to 0 in order to create a new transaction handle or use an already existing handle.
• app: The Handle of the APMApplication representing this application.
• filtervalue: (optional) This value is used to match a filter of a started Software-Telemetry session. You should register filter values used by calling APMRegisterFilterValue (see “Method APMRegisterFilterValue (C/C++)”)

Return Value:

This function returns the transaction handle for the current or currently created transaction context.

Method APMTxAttachContext (C/C++)

Call APMTxAttachContext to restore the context acquired through APMGetContext or APMTxGetContext in another thread or process (see “Passing Context” and “Method APMGetContext (C/C++)”). You can attach to an already existing transaction context or create a new transaction context which is returned by APMTxAttachContext to pass to other explicit transaction functions.

Parameters:

• tx: Set this value to 0 in order to create a new transaction handle or use an already existing handle.
• app: The Handle of the APMApplication representing this application.
• context: The context which you want to attach to.

Return Value:

This function returns the transaction handle for the current or currently created transaction context.

Method APMTxGetContext (C/C++)

Call the APMTxGetContext-method to get a new context handle for the current transaction context, analogously to APMGetContext.

Parameters:

• tx: The transaction handle of the current transaction context.
• context: APMGetContext creates a context at the location pointed to by context.

Return Value:

• If the function succeeds, the return value is 1 and a context has been saved to the location which context pointed to.
• If no context has been created, the return value is 0.

Method APMTxGetSyncMark (C/C++)

Call the APMTxGetSyncMark-method to get a synchronization handle that can be passed to another thread/process/module to synchronize control flow, same as APMGetSyncMark, for the current transaction context.

Parameters:

• tx: The transaction handle of the current transaction context.
• context: APMGetSyncMark creates a sync mark at the location pointed to by context.

Return Value:

• If the function succeeds, the return value is 1 and a sync mark has been saved to the location which context pointed to.
• If no sync-mark has been created, the return value is 0.

Method APMTxSetSyncMark (C/C++)

Call APMTxSetSyncMark to pass a sync mark you got from APMGetSyncMark or APMTxGetSyncMark for synchronizing the sequence of events (see “Synchronizing Timeline with SyncMarks” and “Method APMGetSyncMark (C/C++)”).

Parameters:

• tx: The transaction handle of the current transaction context.
• context: The sync mark which you want to sync with.

Return Value:

This function does not return any value.

Method APMTxReleaseContext (C/C++)

Call APMTxReleaseContext with the current transaction handle to finish logging and exit the context, analogously to APMReleaseContext.

Parameters:

• tx: The transaction handle of the current transaction context.

Return Value:

This function does not return any value.

Method APMTxHasActiveContext (C/C++)

Call APMTxHasActiveContext to test if a software-telemetry session is active for some logging level for the current transaction context, analogously to APMHasActiveContext.

Parameters:

• tx: The transaction handle of the current transaction context.
• level: The event level of the event you prepare parameters for.

Return Value:

• The return value is non-zero if the event will be logged.

Method APMTxEvent (C/C++)

Call the APMTxEvent function to log an event without parameters for the current transaction context.

Parameters:

• tx: The transaction handle of the current transaction context.
• The APMTxEvent function has the same 4 base parameters as APMEvent.

Return Value:

This function does not return any value.

Method APMTxEventArgs (C/C++)

Use APMTxEventArgs to log an event for the current transaction context with various parameters, which must be passed in a predefined format.

Parameters:

• tx: The transaction handle of the current transaction context.
• The APMTxEventArgs function has the 4 base parameters (see “Event Functions (C/C++)”).
• paramCount: The number of parameters you want to pass to this function.
• paramTypes: This is an array containing the types of the parameters. The size of the array is equal to paramCount.
• paramValues: This pointer points to the continuous memory region containing the parameters.
• paramValueSize: This is the size of the memory region containing the parameter values (paramValues).

Return Value:

This function does not return any value.

Method APMTxEventParam (C/C++)

Call the APMTxEventParam-method to log events with a generic parameter structure analogously to APMEventParam for the current transaction context.

Parameters:

• tx: The transaction handle of the current transaction context.
• The APMTxEventParam function has the 4 base parameters (see “Event Functions (C/C++)”).
• param: This is the handle you obtained from a call to APMParamInit.

Return Value:

This function does not return any value.

Method APMTxEventStr (C/C++)

Use APMTxEventStr to log an event with an additional string value as parameter.

Parameters:

• tx: The transaction handle of the current transaction context.
• The APMTxEventStr function has the 4 base parameters (see “Event Functions (C/C++)”).
• param: Pointer to null-terminated, utf8-encoded string. The maximum string length allowed is 32768 Byte.

Return Value:

This function does not return any value.

Method APMTxReport (C/C++)

Call APMTxReport to create a new feedback report, see "Method APMReport (C/C++)".

Parameters:

• tx: The transaction handle of the current transaction context.
• app: The Handle of the APMApplication representing this application.
• filtervalue: filtervalue to match requests with.
• reportkey: A key value may be generated by the calling application to associate further descriptions to a feedback. If empty, a new feedback report will be generated on each call and no further information may be attached to the feedback.
• description: Textual description of the feedback entered by the user or generated by the application. The maximum length of the description is 32768 Bytes.

Return Value:

This function does not return any value.

Method APMTxReportValue (C/C++)

Call APMTxReportValue to add a key/value pair to an existing report.

Parameters:

• tx: The transaction handle of the current transaction context.
• app: The Handle of the APMApplication representing this application.
• reportkey: reportkey matches the reportkey of the APMReport function to associate the value with the report session.
• key: A key describes the meaning of the value. Only one value can be associated to a single key in one report session.
• value: Text (max. 32 kBytes).

Return Value:

This function does not return any value.