Login Register Free Account
Trackerbird SDK v3 for Mac OS (Objective-C)
TBApp Class Reference
Inheritance diagram for TBApp:

Class Methods

Basic SDK Control


(void) + start:completionBlock:
 
(void) + start:completionBlock:doSync:receiveReachout:
 
(void) + stop:
 
(void) + stopAndDoSyncWithTimeout:completionBlock:
 
(void) + sessionStartWithID:completionBlock:
 
(void) + sessionStopWithID:completionBlock:
 
Synchronization


(void) + sync:
 
(void) + sync:receiveReachout:
 
(void) + startAutoSync
 
(void) + startAutoSyncReceivingReachout:
 
(void) + stopAutoSync
 
Event Tracking


(void) + eventTrackWithName:category:value:sessionID:allowExtendedNames:completionBlock:
 
(void) + eventTrackWithName:category:value:sessionID:completionBlock:
 
Exception Tracking


(void) + exceptionTrackWithClassName:methodName:message:stackTrace:completionBlock:
 
(void) + exceptionTrackWithClassName:methodName:exception:completionBlock:
 
(void) + exceptionTrackWithClass:selector:message:stackTrace:completionBlock:
 
(void) + exceptionTrackWithClass:selector:exception:completionBlock:
 
Manual Message Retrieval


(void) + messageCheck:
 
(void) + messageCheckWithType:completionBlock:
 
Checking for Software Updates


(void) + versionCheck:
 
License Management


(void) + keyCheck:completionBlock:
 
(void) + keyChange:completionBlock:
 
(void) + setLicenseInformationWithKeyType:whitelistedStatus:expiredStatus:blacklistedStatus:activatedStatus:completionBlock:
 
(void) + setLicenseInformationWithKeyType:completionBlock:
 
SDK Status Checks


(void) + connectionCheckToURL:completionBlock:
 
Privacy Settings


(void) + privacyMode:
 
(void) + setPrivacyMode:completionBlock:
 
Custom Filters


(void) + setCustomProperty:atIndex:completionBlock:
 
Other


(void) + updateConfig:completionBlock:
 

Method Documentation

+ (void) connectionCheckToURL: (NSString *)  url
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

This method allows you to test your application’s connectivity with the Trackerbird server and to confirm that your callhome URL is active and operational (for debugging purposes when using a custom callhome URL). You do NOT need to call this method before other API calls since this would cause unnecessary traffic on your clients’ machines. Instead, you should check the return types by each API call since every API call which requires server communication does it’s own connection status check and returns any connection errors as part of it’s return type.

Parameters
urlThe URL against which to test connectivity (usually your callhome URL)
completionBlockAn Objective-C Block, which is called when the SDK completes the connection check. This block receives one prameter: status.
statusA value from TBResultStatus enum.
+ (void) eventTrackWithName: (NSString *)  name
category: (NSString *)  category
value: (id)  value
sessionID: (NSString *)  sessionID
allowExtendedNames: (BOOL)  allowExtendedNames
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

Track an event.

Parameters
nameThe name of the event to be tracked. This parameter must not be nil.
categoryThe name of the group/category that this event forms part of. This parameter is optional. This parameter may be nil.
valueAn optional numeric or string value that can contain data related to an event such as how long a function took to execute or how much disk space it used to store its output. This parameter may be nil. This parameter must be instance of NSNumber or NSString.
sessionIDIf multiple user sessions are supported within the application, this should contain the unique ID that refers to the user session in which the event occurred. If the application supports only a single session, then pass nil to this parameter.
allowExtendedNamesIf set to YES - event and category names are limited to 256 chars, otherwise if set to NO - they are limited to 40 and 50 combined
completionBlockAn Objective-C Block, which is called when the SDK completes the event track. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
[TBConfig multiSessionEnabled]
+ (void) eventTrackWithName: (NSString *)  name
category: (NSString *)  category
value: (id)  value
sessionID: (NSString *)  sessionID
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

Track an event.

Parameters
nameThe name of the event to be tracked. This parameter must not be nil.
categoryThe name of the group/category that this event forms part of. This parameter is optional. This parameter may be nil.
valueAn optional numeric or string value that can contain data related to an event such as how long a function took to execute or how much disk space it used to store its output. This parameter may be nil. This parameter must be instance of NSNumber or NSString.
sessionIDIf multiple user sessions are supported within the application, this should contain the unique ID that refers to the user session in which the event occurred. If the application supports only a single session, then pass nil to this parameter.
completionBlockAn Objective-C Block, which is called when the SDK completes the event track. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
[TBConfig multiSessionEnabled]
+ (void) exceptionTrackWithClass: (Class)  cls
selector: (SEL)  selector
exception: (NSException *)  exception
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

Track an instance of NSException based on provided custom class and selector. The message is constructed from the exception's name and reason.

Parameters
clsThe class, which catched the exception.
selectorThe selector, where the exception is catched.
exceptionAn instance of NSException.
stackTraceA stackTrace of the exception. This parameter may be nil.
completionBlockAn Objective-C Block, which is called when the SDK completes the exception track. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
+exceptionTrackWithClassName:methodName:message:stackTrace:completionBlock:
+exceptionTrackWithClassName:methodName:exception:completionBlock:
+exceptionTrackWithClass:selector:message:stackTrace:completionBlock:
+exceptionTrackWithClass:selector:exception:completionBlock:
+ (void) exceptionTrackWithClass: (Class)  cls
selector: (SEL)  selector
message: (NSString *)  message
stackTrace: (NSString *)  stackTrace
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

Track an exception based on provided custom class, selector and message.

Parameters
clsThe class, which catched the exception.
selectorThe selector, where the exception is catched.
messageA message, describing the exception.
completionBlockAn Objective-C Block, which is called when the SDK completes the exception track. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
+exceptionTrackWithClassName:methodName:message:stackTrace:completionBlock:
+exceptionTrackWithClassName:methodName:exception:completionBlock:
+exceptionTrackWithClass:selector:message:stackTrace:completionBlock:
+exceptionTrackWithClass:selector:exception:completionBlock:
+ (void) exceptionTrackWithClassName: (NSString *)  className
methodName: (NSString *)  methodName
exception: (NSException *)  exception
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

Track an instance of NSException based on provided custom name and method name. The message is constructed from the exception's name and reason.

Parameters
classNameThe name of the class, which catched the exception.
methodNameThe name of the method, where the exception is catched.
exceptionAn instance of NSException.
completionBlockAn Objective-C Block, which is called when the SDK completes the exception track. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
+exceptionTrackWithClassName:methodName:message:stackTrace:completionBlock:
+exceptionTrackWithClassName:methodName:exception:completionBlock:
+exceptionTrackWithClass:selector:message:stackTrace:completionBlock:
+exceptionTrackWithClass:selector:exception:completionBlock:
+ (void) exceptionTrackWithClassName: (NSString *)  className
methodName: (NSString *)  methodName
message: (NSString *)  message
stackTrace: (NSString *)  stackTrace
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

Track an exception based on provided custom name, method name, message and stackTrace. This is the core method of the exception tracking. All other methods in that group are provided for easier usage, depending on the needs, since at the end they call this one.

Parameters
classNameThe name of the class, which catched the exception.
methodNameThe name of the method, where the exception is catched.
messageA message, describing the exception.
stackTraceA stackTrace of the exception. This parameter may be nil.
completionBlockAn Objective-C Block, which is called when the SDK completes the exception track. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
+exceptionTrackWithClassName:methodName:message:stackTrace:completionBlock:
+exceptionTrackWithClassName:methodName:exception:completionBlock:
+exceptionTrackWithClass:selector:message:stackTrace:completionBlock:
+exceptionTrackWithClass:selector:exception:completionBlock:
+ (void) keyChange: (NSString *)  key
completionBlock: (void(^)(TBLicenseResult *licenseResult, TBResultStatus status))  completionBlock 

This method should be called when an end user is trying to enter a new license key into your application and you would like to confirm that the key is in fact valid (i.e. not blacklisted). The method is very similar to the +keyCheck:completionBlock: method, however rather than just being a passive license check, it also registers the new key with the server and associates it with this particular client installation.

Parameters
keyThe license key to be tested.
completionBlockAn Objective-C Block, which is called when the SDK completes the version check. This block receives two prameters: licenseResult and status.
licenseResultAn instance of TBLicenseResult.
statusA value from TBResultStatus enum.

Code Example:

Test a license key [TBAppPrivateOBJC keyChange:"<Your new="" key>="">" completionBlock:^(TBLicenseResult *licenseResult, TBResultStatus status) { if(status = TBResultStatusOK) { check the blacklisted status switch(licenseResult.blacklistedStatus) { case TBLicenseStatusNA: NSLog("Status not available"); break;

case TBLicenseStatusFalse: NSLog("New Key is NOT blacklisted"); break;

case TBLicenseStatusTrue: NSLog("New Key is blacklisted"); break; }

check the other statuses ... } else { NSLog("Failed to invoke the method"); } }

See also
TBLicenseResult
+keyCheck:completionBlock:
+ (void) keyCheck: (NSString *)  key
completionBlock: (void(^)(TBLicenseResult *licenseResult, TBResultStatus status))  completionBlock 

By using this method, your software can validate a license key (entered by your client) with the blacklist stored on the Trackerbird server.

Parameters
keyThe license key to be tested.
completionBlockAn Objective-C Block, which is called when the SDK completes the version check. This block receives two prameters: licenseResult and status.
licenseResultAn instance of TBLicenseResult.
statusA value from TBResultStatus enum.

Code Example:

Test a license key [TBAppPrivateOBJC keyCheck:"<Your product="" key>="">" completionBlock:^(TBLicenseResult *licenseResult, TBResultStatus status) { if(status = TBResultStatusOK) { check the blacklisted status switch(licenseResult.blacklistedStatus) { case TBLicenseStatusNA: NSLog("Status not available"); break;

case TBLicenseStatusFalse: NSLog("Key is NOT blacklisted"); break;

case TBLicenseStatusTrue: NSLog("Key is blacklisted"); break; }

check the other statuses ... } else { NSLog("Failed to invoke the method"); }

}

See also
TBLicenseResult
+keyChange:completionBlock:
+ (void) messageCheck: (void(^)(TBMessageResult *messageResult, TBResultStatus status))  completionBlock

Requests a manual ReachOut™ message from the server. This can be either a plain text message or a URL, depending on what messages are waiting on the server.

Parameters
completionBlockAn Objective-C Block, which is called when the SDK completes the message check. This block receives two prameters: messageResult and status
messageResultAn instance of TBMessageResult.
statusA value from TBResultStatus enum.

Code Example:

    [TBApp messageCheck:^(TBMessageResult *messageResult, TBResultStatus status)
    {
        if(status == TBResultStatusOK)
        {
            if(messageResult.messagesCount > 0)
            {
                NSLog(@"This is your message %@", messageResult.message);
            }
            else
            {
                NSLog(@"No message");
            }
        }
    }];
See also
TBMessageResult
+ (void) messageCheckWithType: (TBMessageType)  messageType
completionBlock: (void(^)(TBMessageResult *messageResult, TBResultStatus status))  completionBlock 

Requests a manual ReachOut™ message from the server while specifying the type of message that is needed.

Parameters
messageTypeThe message type needed is to be sent in the messageType parameter, and can be one of the TBMessageType enum values, declared in TBMessageResult.
completionBlockAn Objective-C Block, which is called when the SDK completes the message check. This block receives two prameters: messageResult and status.
messageResultAn instance of TBMessageResult.
statusA value from TBResultStatus enum.

Code Example:

    [TBApp messageCheckWithType:TBMessageTypeAll completionBlock:^(TBMessageResult *messageResult, TBResultStatus status)
    {
        if(status == TBResultStatusOK)
        {
            if(messageResult.messagesCount > 0)
            {
                NSLog(@"This is your message %@", messageResult.message);
            }
            else
            {
                NSLog(@"No message");
            }
        }
    }];
See also
TBMessageResult
+ (void) privacyMode: (void(^)(TBPrivacyMode privacyMode, TBResultStatus status))  completionBlock

Get the level of privacy.

Parameters
completionBlockAn Objective-C Block, which is called in order to return the privacy mode. This block receives two prameters: privacyMode and status.
privacyModeThe privacy mode over which the SDK currently operate.
statusA value from TBResultStatus enum.

The Trackerbird SDK supports 3 different Privacy settings that give you control on what type of anonymous data should be collected form the end user’s machine, based on whether the user opted in or out of your Customer Experience Improvement. To read more about privacy and what data is collected by each privacy level, please refer to this Kbase article: http://helpdesk.trackerbird.com/knowledgebase.php?article=1

The Default Value is TBPrivacyModeOff

+ (void) sessionStartWithID: (NSString *)  sessionID
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

This method, in conjunction with +sessionStopWithID: should be called only if multiSessionEnabled in the TBConfig constructor has been set to YES.

When a new user session is started, the Trackerbird SDK needs to be informed so that events that happen within this session can be logged. The time when this method is called is also used to calculate the session duration.

Parameters
sessionIDThis parameter should contain a unique ID that refers to the user session that is being started. This same ID should later be used for event tracking.
completionBlockAn Objective-C Block, which is called when the SDK completes the session start. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
+sessionStopWithID:completionBlock:
+ (void) sessionStopWithID: (NSString *)  sessionID
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

This method, in conjunction with +sessionStartWithID: should be called only if multiSessionEnabled in the TBConfig constructor has been set to YES.

When a user session has been closed, this method should be called so that Trackerbird can calulcate the duration of the user session. In case this method is never called, eventually this session will be considered as “timed-out”, and the time of the last recorded event will be assumed to be the time when the session was closed.

When a new user session is started, the Trackerbird SDK needs to be informed so that events that happen within this session can be logged. The time when this method is called is also used to calculate the session duration.

Parameters
sessionIDThis parameter should contain a unique ID that refers to the user session that is being stopped. This must be the same same ID that was used earlier when calling +sessionStopWithID:.
completionBlockAn Objective-C Block, which is called when the SDK completes the session stop. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
TBConfig
[TBConfig initWithURL:productID:productVersion:productBuildNumber:multiSessionEnabled:productEdition:productLanguage:]
+sessionStopWithID:completionBlock:
+ (void) setCustomProperty: (NSString *)  property
atIndex: (NSUInteger)  index
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

This method sets a value of a custom filter propery at specified index;

Parameters
propertyThe namame of the property. If nil is provided, then any existing value is removed.
indexThe index of the property. This value must be from 1 ot 20.
completionBlockAn Objective-C Block, which is called when the SDK completes the custom property update. This block receives one prameter: status
statusA value from TBResultStatus enum.
+ (void) setLicenseInformationWithKeyType: (TBKeyType)  keyType
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

Set The Product's License Information (Key Type only).

Parameters
keyTypeThe New Key Type.
completionBlockAn Objective-C Block, which is called when the SDK completes the license info update. This block receives one prameter: status

This method will update only the key type.

See also
TBLicenseResult
+ (void) setLicenseInformationWithKeyType: (TBKeyType)  keyType
whitelistedStatus: (TBLicenseStatus)  whitelistedStatus
expiredStatus: (TBLicenseStatus)  expiredStatus
blacklistedStatus: (TBLicenseStatus)  blacklistedStatus
activatedStatus: (TBLicenseStatus)  activatedStatus
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

Set The Product's License Information.

Parameters
completionBlockAn Objective-C Block, which is called when the SDK completes the license info update. This block receives one prameter: status
statusA value from TBResultStatus enum.

This method accepts TBKeyType and TBLicenseStatus types as parameters. For more information about they values - see TBLicenseResult.

See also
TBLicenseResult
+ (void) setPrivacyMode: (TBPrivacyMode)  privacyMode
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

Set the level of privacy.

Parameters
privacyModeOne of the privacy modes from the TBPrivacyMode.
completionBlockAn Objective-C Block, which is called when the SDK completes the privacy mode update. This block receives one prameter: status
statusA value from TBResultStatus enum.

The Trackerbird SDK supports 3 different Privacy settings that give you control on what type of anonymous data should be collected form the end user’s machine, based on whether the user opted in or out of your Customer Experience Improvement. To read more about privacy and what data is collected by each privacy level, please refer to this Kbase article: http://helpdesk.trackerbird.com/knowledgebase.php?article=1

The Default Value is TBPrivacyModeOff

+ (void) start: (TBConfig *)  config
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

This method must be called before utilizing any of the other functionality of the Trackerbird SDK. This method requires an object of type TBConfig which contains the SDK configuration. For further detail, refer to the SDK Configuration page. This call do a sync and receive reachout if available.

Parameters
configAn TBConfig instance.
completionBlockAn Objective-C Block, which is called when the SDK completes the start. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
TBConfig
+stop:

For Cocoa Applications, the best place to put the +start: call is in -applicationDidFinishLaunching: of your NSApplicationDelegate implemetation.

+ (void) start: (TBConfig *)  config
completionBlock: (void(^)(TBResultStatus status))  completionBlock
doSync: (BOOL)  doSync
receiveReachout: (BOOL)  receiveReachout 

This method must be called before utilizing any of the other functionality of the Trackerbird SDK. This method requires an object of type TBConfig which contains the SDK configuration. For further detail, refer to the SDK Configuration page.

Parameters
configAn TBConfig instance.
completionBlockAn Objective-C Block, which is called when the SDK completes the start. This block receives one prameter: status
statusA value from TBResultStatus enum.
doSyncA BOOL value which determeni wherever to do a sync after the start.
receiveReachoutA BOOL value which determine wherever to receive reachout during a sync. This value is ignored if doSync is NO.
See also
TBConfig
+stop:

For Cocoa Applications, the best place to put the +start: call is in -applicationDidFinishLaunching: of your NSApplicationDelegate implemetation.

+ (void) startAutoSync

The Trackerbird SDK gives you the option to launch a separate thread that will perform an automatic sync with the server at a regular intervals. This is usually only required for applications running as background services or web services whose running cycle (session runtime duration) spans over 6 hours. Before using this method please make sure you read the section on Caching and Synchronizing. This call, also receives a reachout if available.

Once you call +startAutoSync you may use +stopAutoSync to stop the automatic synchronization process.

See also
+sync:
+stopAutoSync
+ (void) startAutoSyncReceivingReachout: (BOOL)  receiveReachout

The Trackerbird SDK gives you the option to launch a separate thread that will perform an automatic sync with the server at a regular intervals. This is usually only required for applications running as background services or web services whose running cycle (session runtime duration) spans over 6 hours. Before using this method please make sure you read the section on Caching and Synchronizing.

Parameters
receiveReachoutA BOOL value which determine wherever to receive reachout during sync.

Once you call +startAutoSync you may use +stopAutoSync to stop the automatic synchronization process.

See also
+sync:
+stopAutoSync
+ (void) stop: (void(^)(TBResultStatus status))  completionBlock

This method should always be called on the exit point of your application. This will help the Trackerbird server keep track of when your application was closed to accurately calculate session runtime duration and provide you with reports based on application usage statistics. Calling +stop before your application terminates will also tell the Trackerbird server that your application was terminated gracefully without any unhandled exceptions.

Unlike most functions in the SDK, this function is synchronous, which means it returns only once finished. Due to this fact, it is recommended to close/hide the application UI before calling this function. By default, during this function, the SDK syncs all data with the server, and this is what might take a bit long during.

Parameters
completionBlockAn Objective-C Block, which is called when the SDK completes the stop. This block receives one prameter: status
statusA value from TBResultStatus enum.

For Cocoa Applications, the best place to put the +stop call is in -applicationWillTerminate: of your NSApplicationDelegate implemetation.

See also
+start:completionBlock:
+ (void) stopAndDoSyncWithTimeout: (NSInteger)  syncTimeout
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

This method should always be called on the exit point of your application. This will help the Trackerbird server keep track of when your application was closed to accurately calculate session runtime duration and provide you with reports based on application usage statistics. Calling +stop before your application terminates will also tell the Trackerbird server that your application was terminated gracefully without any unhandled exceptions.

Unlike most functions in the SDK, this function is synchronous, which means it returns only once finished. Due to this fact, it is recommended to close/hide the application UI before calling this function. By default, during this function, the SDK syncs all data with the server, and this is what might take a bit long during.

Parameters
syncTimeoutInstructs the SDK on whether to sync with the server before returning and the maximum number of seconds to allow the SDK to sync. Any negative value will prevent syncing, 0 will do sync and wait until finished, any positive value will do sync and wait for the time (seconds) of the given value.
completionBlockAn Objective-C Block, which is called when the SDK completes the stop. This block receives one prameter: status
statusA value from TBResultStatus enum.

For Cocoa Applications, the best place to put the +stop call is in -applicationWillTerminate: of your NSApplicationDelegate implemetation.

See also
+start:completionBlock:
+ (void) stopAutoSync

Use this method to stop the automatic synchronization with the server which can be started by calling on the +startAutoSync method.

See also
+sync:
+startAutoSync
+ (void) sync: (void(^)(TBResultStatus status))  completionBlock

This function will forcefully synchronize all cached data from the client machine with the Trackerbird server. The method has no return value and has no parameters. It runs asynchronously so there is no need to place this method inside of a separate thread . This call, also receives a reachout if available.

Parameters
completionBlockAn Objective-C Block, which is called when the SDK completes the sync. This block receives one prameter: status
statusA value from TBResultStatus enum.

This method is not required and in fact should be avoided. Both the SDK and the server can reject a sync request from occuring even if this is forced by the developer. This is done to prevent abuse and unnecessary server load if +sync is called too frequently.

See also
+startAutoSync
+stopAutoSync
+ (void) sync: (void(^)(TBResultStatus status))  completionBlock
receiveReachout: (BOOL)  receiveReachout 

This function will forcefully synchronize all cached data from the client machine with the Trackerbird server. The method has no return value and has no parameters. It runs asynchronously so there is no need to place this method inside of a separate thread .

Parameters
completionBlockAn Objective-C Block, which is called when the SDK completes the sync. This block receives one prameter: status
statusA value from TBResultStatus enum.
receiveReachoutA BOOL value which determine wherever to receive a reachout popup on this sync.

This method is not required and in fact should be avoided. Both the SDK and the server can reject a sync request from occuring even if this is forced by the developer. This is done to prevent abuse and unnecessary server load if +sync is called too frequently.

See also
+startAutoSync
+stopAutoSync
+ (void) updateConfig: (TBConfig *)  config
completionBlock: (void(^)(TBResultStatus status))  completionBlock 

This method updates the current configuration over which the SDK operate. The update reflects only the optional parameters - productVersion, productBuildNumber, productEdition and productLanguage of TBConfig

Parameters
configAn Instace of TBConfig.
completionBlockAn Objective-C Block, which is called when the SDK completes the config update. This block receives one prameter: status
statusA value from TBResultStatus enum.
See also
TBConfig
+ (void) versionCheck: (void(^)(TBVersionResult *versionResult, TBResultStatus status))  completionBlock

This method is used to implement a check for updates system for your software.

Parameters
completionBlockAn Objective-C Block, which is called when the SDK completes the version check. This block receives two prameters: versionResult and status.
versionResultAn instance of TBVersionResult.
statusA value from TBResultStatus enum.
See also
TBVersionResult
Warning
You should not perform any kind of "Software Update" if you are going to sumbit your application to the Mac App Store, since Apple forbids any kind of auto updates for applications that resides into the Mac App Store. In such cases you should use this functionality for informative purposes only.

The documentation for this class was generated from the following file: