/**
 * Appcelerator Platform SDK
 * Copyright (c) 2014 by Appcelerator, Inc. All Rights Reserved.
 * Proprietary and Confidential - This source code is not for redistribution
 */

#import <Foundation/Foundation.h>

/*!
 The APSPerformance class provides a centralized point of control and
 coordination for real-time crash reporting and app monitoring to capture errors
 and provide valuable diagnostic information of your mobile application. This
 information is sent to your Performance Dashboard in real-time.
 
 All that is required to start collecting this valuable data and visualizing it
 on your Performance Dashboard is calling the method configureWithAppKey: on 
 the singleton instance of this class.
 
 The shared instance of this class is thread safe, and may be called from any
 thread.
 
 Your own custom data may be sent to your Performance Dashboard in addition to
 what Appcelerator collects and sends. For example, this is how you would
 display the game level in your app:
 
     [APSPerformance sharedInstance][@"Game Level"] = @(10);
 
 For information on getting started with Appcelerator Platform Services, see
 [Appcelerator Platform Services Native SDKs](http://bit.ly/1gBzl2s).
 */
@interface APSPerformance : NSObject

/*!
 @discussion Returns the singleton instance to the real-time diagnostic service.
 */
+(instancetype) sharedInstance;

/*!
 @discussion Set to NO (the default) to send diagnostic data to your
 Performance Dashboard.
 */
@property (atomic, assign, readwrite, getter=isOptOut) BOOL optOut;

/*!
 @discussion An optional username to help you differentiate metadata for crash
 reports. The maximum length of the username is 32 characters. There is no
 default value, and if no value is set then nil is returned.
*/
@property (atomic, strong, readwrite) NSString *username;

/*!
 @discussion Returns YES if the application crashed on the last launch of your app.
 The value NO is returned if the app crashed on previous launch and optOut was
 set to YES.
 */
@property (atomic, assign, readonly, getter=didCrashOnLastAppLoad) BOOL didCrashOnLastAppLoad;


/*!
 @discussion The unique identifier generated by the Performance Service to
 identify your app's diagnostic data.
 */
@property (atomic, strong, readonly) NSString *uniqueIdentifier;

/*!
 @discussion This is an advanced option that has a suitable default.
 
 Set to NO (the default) to persist breadcrumbs synchronously, which
 provides the most accurate breadcrumb trail leading up to a crash.
 
 Set to YES only if you measure a performance issue with leaving breadcrumbs,
 which may improve the performance of persisting breadcrumbs at the cost of
 possibly loosing some immediately before a crash.
 */
@property (atomic, assign, readwrite, getter=isAsyncBreadcrumbMode) BOOL asyncBreadcrumbMode;

/*!
 @discussion Adds a breadcrumb to a breadcrumb trail in your app, which allows
 you to obtain a playback of events leading up to a crash. The 99 most recent
 breadcrumbs before the occurence of a crash are displayed on your
 Performance Dashboard. A breadcrumb can have a maximum length of 140
 characters.
 @param breadcrumb A breadcrumb to add to the breadcrumb trail.
 */
-(void)leaveBreadcrumb:(NSString*)breadcrumb;

/*!
 Adds an exception you caught to an exception queue that can hold up to five
 exceptions. The tail of this queue is popped and sent to your Performance
 Dashboard once per minute.
 @param exception The exception to add to the queue
 */
-(void)logHandledException:(NSException *)exception;

/*!
 Retrieves a local in-memory cache of custom metadata you have sent to your
 Performance Dashboard. This is an implementation of Custom Keyed Subscripting.
 @param key Key of the value to retrieve.
 */
- (id)objectForKeyedSubscript:(id <NSCopying>)key;

/*!
 @abstract Adds custom metadata to your Performance Dashboard using Custom Keyed Subscripting.
 @discussion For example, this is how you would display the game level of
 your app on your Performance Dashboard:
 
     [APSPerformance sharedInstance][@"Game Level"] = @(10);

 @param obj Value of the metadata. Can either be a string or number.
 @param key Key of the metadata.
 */
- (void)setObject:(id)obj forKeyedSubscript:(id <NSCopying>)key;


@end