Fetching latest commit…
Cannot retrieve the latest commit at this time.
CoreStack v1.0 : README Copyright (c) 2010 Adam Wright Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. CoreStack : An Objective C 2.0 interface to the Stack Exchange API. Also uses http://code.google.com/p/json-framework/ and http://github.com/gabriel/gh-unit/. OVERVIEW This document assumes you've read the beginner material regarding the API at http://stackapps.com/, and are familiar with Objective C. CoreStack is a purely asynchronous API built around requesting object sets from StackExchange sites. The key class structure is: CSSiteDescriptor Describes a Stack Exchange Site, including API endpoints CSAuth Represents the StackAuth site CSSite: Represents a single Stack Exchange site CSObject: Encapsulates an object (User, Comment etc) from a site CSObjectVector: Encapsulates a list of objects from a site CSRequestParams: Encapsulates a request for objects from a site CSRequestToken: Represents a request made of a site, but not yet delivered All CSObject subclasses expose properties that match the structure documented in the API help at http://api.stackapps.com/1.0/help. USAGE: Link all the files outside of the Tests directory, along with the contents of the JSON folder with your application. Link against SystemConfiguration.framework. Then just dive in - a typical usage might be as follows: 0. Change the definition CS_API_KEY in CoreStackConstants to match your API key 1. Create a CSSiteDescriptor via initWithName:andEndPoint:. One such name/end point combination might be @"StackOverflow" and @"http://api.stackoverflow.com" 2. Pass this descriptor to CSSite via initWithDescriptor 3. Write a class conforming to CSObjectRequestDelegate (defined in CSSite.h) 4. Obtain request parameters for user 1200 with [CSUser requestParamsForObjectWithIdentifier:1200] 5. Pass the parameters and your delegate to your site instance via requestObjects:notify:. Store the request token. 6. Wait for your requestComplete:forRequest:error: delegate method to be invoked. If you get bored, call cancelRequest: on CSSite 7. Call [objects first] the delivered results set to see the user. If the passed error is not nil, check CoreStackConstants.h for error codes 8. Examine properties of the delivered user object. You might want to read their comments, so obtain a CSRequestParams via [user requestParamsForComments] and make another request A more involved usage will create a CSAuth instance, and become its delegate to receive notification of all the Stack Exchange sites. You can then use these sites to built CSSite instances. You can see a "real life" usage example at http://sixtoeightapp.com/code/SiteStatisticsView.m / h . It shows how, given a CSSite object, you can use it to request data, receive it, then serialise and deserialise it. NOTES: * The API should work with both garbage collection and manual memory management * There are the barest minimum of (i.e. virtually zero) unit tests in the Tests folder. Expanding this set is a good idea. * The API is only asynchronous. Data download will occur in the background, but all results will be delivered on the main thread * You will need a runloop for this API to function. If you're using UIKit or Application Kit, you've almost certainly got one already * Delegate objects for CSAuth and notification delegates for CSSite are *not* retained. You must unset the CSAuth delegate or call CSSite cancelRequest: if your delegate is about to dealloc * All classes apart from CSSite conform to NSCoding. You are encouraged to serialise objects for state preservation, rather than just storing IDs and mass-downloading them again upon restart. * The easiest way to explore the API is to just read the header files. Look out for requestParamsFor* method signatures (these are both static and instance methods) * All objects are returned in a CSObjectVector - even single results. This matches the Stack Exchange API design. * You should rarely need to create CSRequestParam or CSObject instances yourself. Use provided class and instance methods to build request parameters, and obtain your CSObjects via CSSite requests or NSCoding initFromCoder deserialisations.