Updated doxygen docs. Fixed passing a JSON string to batch. Fixed ret…

…urning attachment ID from upload. Added support for local file paths. Added MACROs to control logging to different levels. Uses ASL for Console logging. Added NSDate subclasses to tell the difference between Dates and DateTimes. More complete unit test coverage. Updated config defaults to values that work better for ASIHTTPRequests. Return the response from startSynchronous. Fixed queue management logic. Limit to 4 concurrent requests by default.
shotgunsoftware · Jun 24, 2011 · 2a330ef · 2a330ef
1 parent 5598fff
commit 2a330ef
Show file tree

Hide file tree

Showing 20 changed files with 653 additions and 346 deletions.
diff --git a/Classes/ClientCapabilities.h b/Classes/ClientCapabilities.h
@@ -5,10 +5,11 @@
 //  Created by Rob Blau on 6/11/11.
 //  Copyright 2011 Laika. All rights reserved.
 //
+/// @file ClientCapabilities.h A structure for storing information about the client.
 
 #import <Foundation/Foundation.h>
 
-@interface ClientCapabilities : NSObject;
+@interface ClientCapabilities : NSObject
 
 @property (retain, readwrite, nonatomic) NSString *platform;
 @property (retain, readwrite, nonatomic) NSString *localPathField;

diff --git a/Classes/ClientCapabilities.m b/Classes/ClientCapabilities.m
@@ -5,6 +5,7 @@
 //  Created by Rob Blau on 6/11/11.
 //  Copyright 2011 Laika. All rights reserved.
 //
+/// @file ClientCapabilities.m Implementation of ClientCapabilities
 
 #import "ClientCapabilities.h"
 

diff --git a/Classes/ServerCapabilities.h b/Classes/ServerCapabilities.h
@@ -5,10 +5,11 @@
 //  Created by Rob Blau on 6/11/11.
 //  Copyright 2011 Laika. All rights reserved.
 //
+/// @file ServerCapabilities.h A structure for storing information about the server.
 
 #import <Foundation/Foundation.h>
 
-@interface ServerCapabilities : NSObject;
+@interface ServerCapabilities : NSObject
 
 @property (assign, readonly, nonatomic) BOOL isDev;
 @property (assign, readonly, nonatomic) BOOL hasPaging;

diff --git a/Classes/ServerCapabilities.m b/Classes/ServerCapabilities.m
@@ -5,6 +5,7 @@
 //  Created by Rob Blau on 6/11/11.
 //  Copyright 2011 Laika. All rights reserved.
 //
+/// @file ServerCapabilities.m Implementation of ServerCapabilities
 
 #import "ServerCapabilities.h"
 

diff --git a/Classes/Shotgun.h b/Classes/Shotgun.h
@@ -5,217 +5,24 @@
 //  Created by Rob Blau on 6/8/11.
 //  Copyright 2011 Laika. All rights reserved.
 //
-
-#pragma mark - Main Page Documentation
-
-/*!
- *
- * @mainpage %Shotgun API
- *
- * @section toc Table of Contents
- * <ul>
- *   <li>@ref Introduction</li>
- *   <li>@ref Installation</li>
- *   <li>@ref Notes</li>
- *   <li>@ref details</li>
- *   <ul>
- *     <li>@ref connecting</li>
- *     <li>@ref finding</li>
- *     <li>@ref modifying</li>
- *     <li>@ref batch</li>
- *     <li>@ref schema</li>
- *     <li>@ref files</li>
- *     <li>@ref requests</li>
- *   </ul>
- *   <li>@ref TODOs</li>
- *   <li>@ref Dependencies</li>
- *   <li>@ref Links</li>
- * </ul>
- *
- * @section Introduction
- * This is an objective c port of the python shotgun api.
- *
- * For complete documentation of how the %Shotgun API works along with
- * tutorials, examples, and other details see:\n
- * https://github.com/shotgunsoftware/python-api/wiki
- *
- * @section Installation
- *  <ul>
- *  <li>Start by downloading the code from https://github.com/shotgunsoftware/objc-api</li>
- *  <li>Copy the files in Classes directory into your project.</li>
- *  <li>Copy the dependencies into your project.\n\n
- *      All the dependencies are included as git submodules in the Dependencies directory.\n
- *      You can either download the dependencies yourself or (if you cloned the project via\n
- *      git rather than downloading the tarball) run 'git submodule init' followed by\n
- *      'git submodule update' to download the projects at the revision as of the writing of\n
- *      this library.\n\n
- *    <ul>
- *      <li><b>json-framework</b> - Copy the files in Classes into your project.</li>
- *      <li><b>asi-http-request</b> (<i>See the <a href="http://allseeing-i.com/ASIHTTPRequest/Setup-instructions">official docs</a> for more in depth instructions).</i>
- *        <ul>
- *          <li>Copy the files in Classes into your project (just the files, the directories are not needed)</li>
- *          <li>Copy the files in External/Reachability into your project.</li>
- *          <li>Link against CFNetwork, SystemConfiguration, MobileCoreServices, CoreGraphics and zlib</li>
- *        </ul>
- *      </li>
- *    </ul>
- *  </li>
- *  </ul>
- *  See the example project under Examples to see what the resulting setup should look like.
- *
- * @section Notes
- *  \li All NSDate objects are assumed to be in UTC (This is the default NSDate behavior).
- *
- * @section details API Details
- *   @subsection connecting Connecting to Shotgun
- *   \code
- *   NSString *url = @"http://mysite.shotgunsoftware.com";
- *   NSString *script = @"example_script";
- *   NSString *key = @"abcdefghijklmnopqrstuvwxyz";
- *   Shotgun *shotgun = [[[Shotgun alloc] initWithUrl:url scriptName:script andKey:key] autorelease];
- *   \endcode
- *
- *   @subsection finding Finding entities
- *   \code
- *   ShotgunRequest *request = 
- *     [shotgun findEntityOfType:@"Version"
- *                   withFilters:@"[[\"code\", \"starts_with\", \"100\"]]"
- *                     andFields:@"[\"code\", \"image\"]"];
- *   [request startSynchronous];
- *   NSArray *results = [request response];
- *   \endcode
- *
- *   @subsection modifying Creating, modifying, deleting, and reviving entities
- *   \code
- *   ShotgunRequest *request = [shotgun createEntityOfType:@"Shot"
- *                                           withData:@"{\"code\": \"s10\", \"description\": \"Shot 10\"}"];
- *   [request startSynchronous];
- *   ShotgunEntity *shot = [request response];
- *   \endcode
- *   \code
- *   ShotgunRequest *request = [shotgun updateEntityOfType:@"Shot"
- *                                             withId:[NSNumber numberWithInt:23]
- *                                           withData:@"{\"description\": \"Shot 20 - More Info\"}"];
- *   [request startSynchronous];
- *   ShotgunEntity *shot = [request response];
- *   \endcode
- *   \code
- *   ShotgunRequest *request = [shotgun deleteEntityOfType:@"Shot" withId:[NSNumber numberWithInt:23]];
- *   [request startSynchronous];
- *   BOOL success = [[request response] boolValue];
- *   \endcode
- *   \code
- *   ShotgunRequest *request = [shotgun reviveEntityOfType:@"Shot" withId:[NSNumber numberWithInt:23]];
- *   [request startSynchronous];
- *   BOOL success = [[request response] boolValue];
- *   \endcode
- *
- *   @subsection batch Batch operations
- *   \code
- *   ShotgunRequest *request = [shotgun batch:@"[" \
- *       "{                                 " \
- *       " \"request_type\": \"create\",    " \
- *       " \"entity_type\":  \"Shot\",      " \
- *       " \"data\": {                      " \
- *       "     \"code\": \"s10\",           " \
- *       "     \"description\": \"Shot 10\" " \
- *       "   }                              " \
- *       "},                                " \
- *       "{\"request_type\": \"delete\", \"entity_type\": \"Shot\", \"entity_id\": 23}" \
- *     ]"];
- *   [request startSynchronous];
- *   NSArray *results = [request response];
- *   \endcode
- *
- *   @subsection schema Meta-Schema queries
- *   \code
- *   ShotgunRequest *request = [shotgun schemaEntityRead];
- *   [request startSynchronous];
- *   NSDictionary *schemaInfo = [request response];
- *   \endcode
- *   \code
- *   ShotgunRequest *request = [shotgun schemaRead];
- *   [request startSynchronous];
- *   NSDictionary *schema = [request response];
- *   \endcode
- *   \code
- *   ShotgunRequest *request = [shotgun schemaFieldReadForEntityOfType:@"Shot" forField:@"sg_status_list"];
- *   [request startSynchronous];
- *   NSDictionary *entitySchema = [request response];
- *   \endcode
- *
- *   @subsection files Uploading and downloading files
- *   \code
- *   NSNumber *attachmentId = [shotgun uploadThumbnailForEntityOfType:@"Shot"
- *                                          withId:[NSNumber numberWithInt:23]
- *                                        fromPath:@"/path/to/the/file.jpg"];
- *   \endcode
- *   \code
- *   NSData *imageData = downloadAttachmentWithId:[NSNumber numberWithInt:201];
- *   \endcode
- *
- *   @subsection requests Using ShotgunRequest Objects
- *   ShotgunRequests can be run either synchronously or asynchronously.
- *
- *   To run a request syncronously simply call startSyncronously:
- *   \code
- *   [request startSyncronous];
- *   \endcode
- *   The request will block the current thread until it is finished and its response is ready.
- *
- *   To run a request asynchronously call startAsynchronous:
- *   \code
- *   [request startAsynchronous];
- *   \endcode
- *   Control will return to the current thread right away.  To process the response to the
- *   request, register callback blocks with request before starting it:
- *   \code
- *   [request setCompletionBlock:^{
- *      id response = [request response];
- *      // Do Stuff with the response
- *   }];
- *   \endcode
- *
- *   The currently supported callbacks are:
- *   \li startedBlock - Called when the request is started.
- *   \li completionBlock - Called when the request has finished.
- *   \li failedBlock - Called when the request failed.
- *
- *   The postProcessBlock is used internally to the API and should not be overridden.
- *
- * @section TODOs
- *   @li Switch from Exceptions to NSErrors
- *   @li Add support for responding to events via delegate SELs
- *   @li Add support for asychronous image field resolution
- *   @li Better API around paging
- *   @li Finish documentation
- *   @li Round out unit tets.  Use <a href="http://www.mulle-kybernetik.com/software/OCMock/">OCMock</a>.
- *   @li Switch to a decent logging system
- *   @li \ref todo "Other inline TODOs"
- *
- * @section Dependencies
- *  \li ASIHTTPRequest: http://allseeing-i.com/ASIHTTPRequest/
- *  \li SBJson: http://stig.github.com/json-framework/
- *  \li GHUnit (only needed to run the unit tests): https://github.com/gabriel/gh-unit
- *
- * @section Links
- * \li Python API: https://github.com/shotgunsoftware/python-api
- * \li Mailing List: https://groups.google.com/group/shotgun-objc-api
- * \li Issues: https://github.com/shotgunsoftware/objc-api/issues
- *
- * Rob Blau <rblau@laika.com>
- *
- */
+/// @file Shotgun.h The main import for the API.  All public Shotgun functionality is defined.
 
 #pragma mark - Interface
 
 #import <Foundation/Foundation.h>
 
+#import "ShotgunDate.h"
 #import "ShotgunEntity.h"
 #import "ShotgunRequest.h"
 
-/** Represents a connection to a shotgun server. */
-@interface Shotgun : NSObject;
+/**
+ * Represents a connection to a shotgun server.
+ *
+ * @todo Implement Authentication
+ * @todo Finish file upload/download asynchronous option
+ * @todo Switch from NSException to NSError
+ */
+@interface Shotgun : NSObject
 
 #pragma mark - Initialize
 
@@ -291,7 +98,6 @@
  * @param entityType An NSString specifying the type of entity to return.
  * @param entityId An NSNumber with the id of the entity to update.
  * @param data An NSDictionary specifying values for fields on the new entity (or an NSString that is well formed JSON describing the same value).
- * @param returnFields An NSArray of NSStrings specifying what fields to return (or an NSString that is well formed JSON describing the same value).
  *
  * @return A ShotgunRequest whose response is a ShotgunEntity representing the created entity populated with the specified @p returnFields.
  */