source: releases/ICeCoffEE/1.4.4b1/ICeCoffEE/SmartCrashReportsAPI.h @ 336

Last change on this file since 336 was 216, checked in by Nicholas Riley, 14 years ago

VERSION: Starting with 1.4.3d1.

APE.icns: Generic APE icon (not sure whether we care).

SmartCrashReportsAPI.[ho]: SCR 1.1.

ICeCoffEEWebKit.m: -elementAtPoint:? isn't in current
development WebKit?; switch to the version in WebHTMLView.

Info-APE Module.plist: Update version to 1.4.3d1.

ICeCoffEE.xcodeproj: Xcode 2 version of project, required fixing
script which copies the APE bundle into the installer. We're still
building for 10.3.9 and later on PowerPC only for this release.

English.lproj/APEInfo.rtfd: Small clarifications, update release notes
and version information.

English.lproj/InfoPlist.strings: Update version to 1.4.3d1.

ICeCoffEEShared.h: Use varargs macros to finally fix the stupid
warnings when ICCF_DEBUG is 0.

ICeCoffEE APE.xcode: Removed.

ICeCoffEETerminal.m: Fixes crash on clicking disabled close/minimize
widgets in Open dialog (invalid super method call) by implementing
overridden methods in the faked superclass.

ape_install: APE 1.5.1.

Info-APEManagerPrefPane.plist: Update version number.

APEMain.m: Implement SCR. Fix a comment typo. Remove some useless
uses of the comma operator so the new warning-less ICapeprintf works.

package-ICeCoffEE.sh: Use new xcodebuild syntax and build layout.
Remove a useless use of the semicolon. Nuke localizations on
development builds.

File size: 15.4 KB
Line 
1/*!
2    @header             SmartCrashReportsAPI
3    @abstract   Contains API definitions to use with Smart Crash Reports.
4    @discussion Smart Crash Reports is an enhancement for the Apple's CrashReporter application introduced in Mac OS X 10.4. It allows 3rd party developers to
5                                register their own match specifiers, and if the crash log the user is about to submit contains the match specifier, the crash log will be
6                                sent to the developer as well as Apple. This greatly enhances the user experience of the OS, and allows developers to receive crashes and improve
7                                their software in a timely manner.
8                               
9                                <p>Smart Crash Reports requires no Application Enhancer or similar "patching" frameworks users have to install; they operate on the InputManager
10                                mechanism that built-in Mac OS X.
11
12                                <p>Smart Crash Reports is completely free to use for both users and developers; <a href="http://www.unsanity.com/">Unsanity</a> is providing it as a
13                                service to the community being certain it will benefit all the users on the platform.
14                               
15                                <p><b>How does Smart Crash Reports work?</b>
16                                <p>Whenever an application crashes on user's computer and they click on the Report... button, Smart Crash Reports analyzes the crash log that is about to be submitted
17                                to Apple. If the crash log is determined to be related to a developer that registered the application or product (Contextual Menu Module, InputManager, or any other type of
18                                system plugin), then the user is given an option to submit the bug report to both that developer and Apple, thus giving the developer the chance to fix the bug in the crashed
19                                product in a timely manner.
20                                <p>For developers, there is two ways to make Smart Crash Reports recognize your product. First, and probably the simplest one, is to add a couple of new keys into the
21                                application's Info.plist file that instruct Smart Crash Reports what to do in case that application crashes. However, this method only works for stand-alone applications and
22                                not plugins.
23                                <p>Second method involves using of the supplied API calls to register a Match Specifier with the system. A match specifier is a simple string (no wildcards or regexp) that contains full
24                                or partial name of developer product(s) CFBundleIdentifier (for example, "com.somecompany."). When an application crashes on user's computer,
25                                Smart Crash Reports system analyzes the crashed thread of the crash log to determine if it contains any
26                                of the match specifiers registered with it. If so, the crash is likely related to the developer who registered the match specifier, so Smart Crash Reports takes the
27                                appropriate action from there on.
28                               
29                                <p><b>How Developer Receives The Crash Reports</b>
30                                <p>Developer can receive the crash reports that Smart Crash Reports detected as belonging to them in either of two ways:
31                                <ul>
32                                        <li>By E-Mail to the address provided during the match specifier registration (Unsanity server will handle the mailing for you)</li>
33                                        <li>By a custom CGI script on your web server that processes CrashReporter logs</li>
34                                </ul>
35
36                                <p><b>So, How to Make My Application Work With Smart Crash Reports so I Receive Crash Logs?</b>
37                                <p>If you develop an application and would like to simply receive all the crash logs related to it, do this:
38                                <ol>
39                                        <li>Obtain an E-mail Ticket ID for the E-mail you wish to receive reports at by going to the following URL: <a href="http://www.unsanity.com/goto/email-ticket/">http://www.unsanity.com/goto/email-ticket/</a>.
40                                        <li>Add the following keys to your application Info.plist:<br/>
41                                                <code>&lt;key&gt;SmartCrashReports_CompanyName&lt;/key&gt;<br/>
42                                                &lt;string&gt;Your Company Name&lt;/string&gt;<br/>
43                                                &lt;key&gt;SmartCrashReports_EmailTicket&lt;/key&gt;<br/>
44                                                &lt;string&gt;SCR-XXXXXXXX&lt;/string&gt;</code><br/>
45                                                Replace "Your Company Name" with a readable (short) company name, and "SCR-XXXXXXXX" with the Email Ticket ID you will receive in the E-mail after performing Step 1.<br/>
46                                        <li>You're all done! If you'd like to use your own CGI to process the crash logs, replace <code>SmartCrashReports_EmailTicket</code> key with the <code>SmartCrashReports_URL</code> key.
47                                        Now your application is successfully registered with the Smart Crash Reports system and you will receive crash logs for it in the mail.
48                                </ol>
49                               
50                                <p>If you are developing a plugin, InputManager, and whatnot, you have to use the API provided to register your Match Specifier:
51                                <ol>
52                                        <li><a href="http://www.unsanity.com/smartcrashreports/">Download</a> the Smart Crash Reports SDK. It will contain two files (among others), <code>SmartCrashReportsAPI.o</code> and <code>SmartCrashReportsAPI.h</code>. Add them to your project.
53                                        <li>Obtain an E-mail Ticket ID for the E-mail you wish to receive reports at by going to the following URL: <a href="http://www.unsanity.com/goto/email-ticket/">http://www.unsanity.com/goto/email-ticket/</a>.
54                                        <li>Somewhere in your application, or plugin, add the following line:<br/>
55                                                <code>UnsanitySCR_RegisterMatchSpecifier(NULL, CFSTR("Your Company Name"), NULL, CFSTR("SCR-XXXXXXXX"), NULL);</code><br/>
56                                                Replace "Your Company Name" with a readable (short) company name, and "SCR-XXXXXXXX" with the Email Ticket ID you will receive in the E-mail after performing Step 2.<br/>
57                                                <i>Note</i>: The best way to call this is after your application has finished launching, such as applicationDidFinishLaunching: in the NSApp delegate for Cocoa apps, or
58                                                whatever for any other types of projects.
59                                        <li>There's no Step 4! Now your product is successfully registered with the Smart Crash Reports system and you will receive crash logs containing the match specifier in the crashed thread in the mail.
60                                </ol>
61                                <p><i>Notes:</i> It is not necessary to register with Smart Crash Reports on every application launch; once you register, it is permanent and will exist until user deletes the
62                                SCR database somehow. However, it takes little speed/memory overhead so you can safely call it on every launch to avoid doing 'is registered already' checks and whatnot.
63                               
64                                <p><b>How to Make a CGI to Accept Crash Reports On Your Site?</b>
65                                <p>If you wish to receive crash reports on your Web site, you can implement the custom Submit URL script that user's CrashReporter.app will contact directly. However,
66                                keep in mind that the following criteria should be met:
67                                <ul>
68                                        <li>Your web server script has to be in the same place over next several years, at the very least, to allow delivery of crash reports to you.
69                                        <li>You are responsible for adjusting the web script if the format CrashReporter.app sends crash reports in changes.
70                                        <li>Your web server should be accessible 24/7 and be on a reasonably fast connection to not delay user's submission process.
71                                </ul>
72                                <p>For the above reasons, it is recommended to <a href="http://www.unsanity.com/goto/email-ticket/">obtain the E-mail ticket</a> from Unsanity and use the E-mail feature
73                                of Smart Crash Reports. Unsanity will make sure the server is accessible, knows how to parse all formats of submissions, and will safely redirect the crash reports to the
74                                email you provide.
75                                <p>If your own Web script is still the way you want to go, here is the list of keys currently known to be passed to the script by the CrashReporter.app in a POST form data:
76                                <ul>
77                                        <li><code>url_from</code>: contains the subject of the crash report, usually "<i>&lt;Some Application&gt; crash</i>"
78                                        <li><code>feedback_comments</code>: user comments they entered in the additional info fields
79                                        <li><code>bug_type</code>: unknown constant, probably determines which POST elements are available; presently 9.
80                                        <li><code>app_name</code>: full crashed application name
81                                        <li><code>app_version</code>: version of the crashed application
82                                        <li><code>os_version</code>: Mac OS X version, in form 10.X.X:BUILD (for example, "<i>10.4.2:8C46</i>")
83                                        <li><code>machine_config</code>: Computer configuration string, for example, "<i>PowerMac7,2 (2048 MB)</i>"
84                                        <li><code>page_source</code>: Contains BASE64-encoded crash report
85                                        <li><code>system_profile</code>: Contains BASE64-encoded property list with a brief system profile of the user's system.
86                                </ul>
87                                <p>Please note that these form keys are subject to change by Apple, so it is your responsibility to adjust the scripts on your Web servers if such thing happens.
88                               
89                                <p><b>What Are The Licensing Terms for Smart Crash Reports and its SDK?</b>
90                                <p>You are free to use and distribute Smart Crash Reports enabled products freely in any form without prior permission from Unsanity, LLC. If you like the system and
91                                would like to return the favor Unsanity is doing to the developer community, link to Smart Crash Reports somewhere on your SCR-enabled product page:<br>
92                                <code>This product uses &lt;a href="http://www.unsanity.com/smartcrashreports/"&gt;Smart Crash Reports&lt;a&gt; by &lt;a href="http://www.unsanity.com/"&gt;Unsanity&lt;a&gt;.</code>
93*/
94
95#pragma once
96#include <CoreFoundation/CoreFoundation.h>
97
98#ifdef __cplusplus
99        extern "C" {
100#endif
101
102/*!
103    @function   UnsanitySCR_RegisterMatchSpecifier
104        @abstract       Registers your match specifier with the Smart Crash Reports system.
105    @discussion Register your match specifier with the Smart Crash Reports system. Once this call is done, crash reports containing inMatchString in the crashed thread
106                                will be submitted to you, either to the submission URL (you have to implement the script on your web server), or to the submission email (Unsanity server will
107                                forward the report to you).
108    @param      inMatchString                                           The product ID string to match or NULL to use the current bundle identifier. Normally, this is a part of a CFBundleIdentifier of your product.
109                                                                                                        For example, if your product CFBundleIdentifier is "com.mycompany.myapp", it is a good idea to set inProductIDMatchString
110                                                                                                        to "com.mycompany.", since it will catch all of the products of your company. If you pass NULL to this argument, an attempt to use
111                                                                                                        CFBundleIdentifier from the main bundle will be used, which is handy for most applications out there, but not acceptable for Contextual
112                                                                                                        Menu Modules, Preference Panes and other plugins.
113        @param          inCompanyName                                           The company name in user-readable format. Smart Crash Reports will substitute "Apple" with this string, so make sure it's
114                                                                                                        not too long. Example: "My Company"
115        @param          inSubmissionURL                                         The full URL to the script on your Web server that will handle the submissions, or NULL if you prefer the crash report to be sent
116                                                                                                        to you via email (in this case, inSubmissionEmail must be not NULL). Example: "http://www.mycompany.com/cgi-bin/processor.cgi"
117        @param          inSubmissionEmailTicket                         The email ticket for email you wish to receive crash report at, or NULL if you are handling it yourself on your web server. If this is set,
118                                                                                                        Unsanity server will handle the submission and email you the crash log. <i>Important:</i> this is NOT the email address. It is a unique
119                                                                                                        email ticket that you have to register with Unsanity by going to
120                                                                                                        <a href="http://www.unsanity.com/goto/email-ticket/">http://www.unsanity.com/goto/email-ticket/</a>. This is done for email verification
121                                                                                                        purposes, and also to not expose your real email to end users, if they peek inside of the SCR database somehow
122        @param          inOptionalCommentsTemplate                      If this argument is not NULL, this string will be inserted into the "Description" field of the CrashReporter dialog.
123                                                                                                        This can be useful if you want to put something like "Put your email here if you wish to be contacted by the developer regarding this
124                                                                                                        crash log", or anything else.
125    @result     One of the following:
126                                <ul>
127                                <li> noErr:                                                     Registration successful. If there is already such a match specifier registered, it is replaced with the fresh information
128                                                                                                        supplied to this call.
129                                <li> paramErr:                                          inSubmissionURL and inSubmissionEmailTicket are NULL, or inMatchString is NULL, or inCompanyName is NULL
130                                <li> cNoMemErr:                                         Not enough memory to perform selected operation.
131                                <li> permErr:                                           Not enough permissions to write changes to disk.
132                                <li> bdNamErr:                                          The match string is malformed, or too wide to be accepted (don't try to register "com.", etc!)
133                                </ul>
134*/
135OSStatus                UnsanitySCR_RegisterMatchSpecifier(CFStringRef inMatchString, CFStringRef inCompanyName, CFStringRef inSubmissionURL, CFStringRef inSubmissionEmailTicket, CFStringRef inOptionalCommentsTemplate);
136
137/*!
138    @function   UnsanitySCR_UnregisterMatchSpecifier
139    @abstract   Unregisters your product(s) with the Smart Crash Reports system.
140    @discussion Unregisters your product(s) with the Smart Crash Reports system. Performing this call will cause Smart Crash Reports to stop submitting bug reports for the
141                                inMatchString provided. Note that for this call to succeed, inMatchString must exactly match the one used in call to UnsanitySCR_RegisterProduct.
142    @param      inMatchString                                           The match string to unregister. This must be the same match string as used in the UnsanitySCR_RegisterProduct call before.
143    @result     One of the following:
144                                <ul>
145                                <li> noErr:                                                     Unregistration successful.
146                                <li> paramErr:                                          inMatchString is NULL
147                                <li> cNoMemErr:                                         Not enough memory to perform selected operation.
148                                <li> permErr:                                           Not enough permissions to write changes to disk.
149                                <li> fnfErr:                                            The provided inMatchString was not found in the Smart Crash Reports database. You can safely ignore this error, as
150                                                                                                        it means that the match string you've provided does not exist already.
151                                </ul>
152*/
153OSStatus                UnsanitySCR_UnregisterMatchSpecifier(CFStringRef inMatchString);
154
155/*!
156    @function   UnsanitySCR_IsMatchSpecifierRegistered
157    @abstract   Query whether the match specifier is registered with the Smart Crash Reports system.
158    @discussion Queries whether the product is registered with the Smart Crash Reports system.
159    @param      inMatchString                                           The match string to query for. Note that SCR will perform partial matches search, too, so for example if you have
160                                                                                                        "com.mycompany" registered, and you query against "com.mycompany.otherapp", this function will return positive result.
161        @param          outOptionalRealMatchString                      If not NULL, this variable will contain the "real" match string that SCR contains in the database. You can
162                                                                                                        use it in calls to UnsanitySCR_UnregisterProduct later, if you want. <i>Important</i>: You are responsible for releasing this
163                                                                                                        value, if you have requested it, and the function returns 1.
164    @result     <ul>
165                                <li> 0:                                                         The match string you have provided is not registered with SCR.
166                                <li> 1:                                                         The match string you have provided is registered with SCR.
167                                <li> -1:                                                        inMatchString is NULL
168                                </ul>
169*/
170int                             UnsanitySCR_IsMatchSpecifierRegistered(CFStringRef inMatchString, CFStringRef* outOptionalRealMatchString);
171
172/*
173        These are the keys defined for the Info.plist of the Application. Please look in the UnsanitySCR_RegisterMatchSpecifier documentation for the explanation of which is which.
174*/
175
176#define                 kUnsanitySCR_InfoPlist_CompanyName                                      CFSTR("SmartCrashReports_CompanyName")
177#define                 kUnsanitySCR_InfoPlist_SubmissionURL                            CFSTR("SmartCrashReports_URL")
178#define                 kUnsanitySCR_InfoPlist_SubmissionEmailTicket            CFSTR("SmartCrashReports_EmailTicket")
179#define                 kUnsanitySCR_InfoPlist_CommentsTemplate                         CFSTR("SmartCrashReports_CommentsTemplate")
180
181#ifdef __cplusplus
182        }
183#endif
Note: See TracBrowser for help on using the repository browser.