DropIO Class Reference

DropIO class which provides static DropIODrop factory methods. More...

#import <DropIO.h>

Static Public Member Functions
(void)	+ setAPIKey:
	Sets the Drop.io API key.
(NSString *)	+ APIKey
	Get the API key.
(BOOL)	+ checkAPIKey
	Check that the Drop.io API key has been set.
(NSArray *)	+ parseResponseFromURL:fromNodeName:toObject:parseError:
	Parses Drop.io API response data returned from the given URL.
(NSArray *)	+ parseResponse:fromNodeName:toObject:parseError:
	Parses the Drop.io API response contained in the given NSData object.
(DropIODrop *)	+ dropOperation:atUrl:withParameters:
	Basic bottleneck method for Drop.io RESTful drop operations.
(DropIODrop *)	+ dropWithRandomName
	Creates a new drop with a random name and default properties.
(DropIODrop *)	+ dropWithName:
	Creates a new drop with the given name.
(DropIODrop *)	+ dropWithName:andPassword:
	Creates a new drop with the given name and admin password.
(DropIODrop *)	+ dropWithParameters:
	Creates a new drop with the given parameters.
(NSURL *)	+ URLForDropNamed:withToken:
	Returns an NSURL object pointing to the Drop.io API URL for the drop with the given name and security token.
(DropIODrop *)	+ findDropNamed:error:
	Finds an existing drop with the given name and no authentication.
(DropIODrop *)	+ findDropNamed:withToken:error:
	Find an existing drop with the given name and security token or password.
(DropIODrop *)	+ findDropAtAPIURL:error:
	Find an existing drop given the drop.io API URL.
(NSString *)	+ dropNameFromDropURL:
	Returns a string containing a drop name given a drop.io drop URL.
(DropIODrop *)	+ findDropAtDropURL:error:
	Find an existing drop from a (non-API) Drop.io drop URL.
(void)	+ updateDropNamed:withParameters:
	Updates an existing drop with the given parameters.
(void)	+ deleteDropNamed:withParameters:
	Deletes an existing drop with the given parameters Sets lastError if an API error occurs.
(NSError *)	+ lastError
	Returns the last error generated from a DropKit API call.
(void)	+ setLastError:
	Sets the last DropKit error to the given NSError object.

---

Detailed Description

DropIO class which provides static DropIODrop factory methods.

---

Member Function Documentation

+ (NSString *) APIKey

Get the API key.

Returns:

NSString containing the Drop.io API key value to use in requests.

Referenced by DropIODrop::delete, DropIOAsset::delete, DropIODrop::docWithFilename:data:mimeType:, DropIODrop::linkWithTitle:url:description:, DropIODrop::noteWithTitle:contents:, DropIOAsset::sendToDropNamed:, DropIOAsset::sendToEmail:message:, DropIOAsset::sendToFax:, DropIODrop::update, DropIOAsset::update, DropIODrop::URLForAssetNamed:, DropIODrop::URLForAssetsPage:, and URLForDropNamed:withToken:.

+ (BOOL) checkAPIKey

Check that the Drop.io API key has been set.

DropKit requires the API key value to be set for API calls to work correctly.

Returns:

Boolean true if the API key has been set.

See also:

+ setAPIKey:

+ APIKey

Referenced by dropOperation:atUrl:withParameters:.

+ (void) deleteDropNamed:		(NSString*)	dropName
withParameters:		(NSDictionary*)	params

Deletes an existing drop with the given parameters Sets lastError if an API error occurs.

Parameters:

	dropName	NSString containing the name of the drop to be deleted.
	params	NSDictionary containing name-value pairs specifying the required properties for deleting the drop. See the Drop.io API documentation for parameter details.

Referenced by DropIODrop::delete.

+ (NSString *) dropNameFromDropURL:

(NSURL*)

dropURL

Returns a string containing a drop name given a drop.io drop URL.

Strips the protocol and hostname from the absolute path of the URL.

Parameters:

dropURL

NSURL instance pointing to a drop.io drop URL.

Returns:

An autoreleased NSString containing the drop name.

Referenced by findDropAtDropURL:error:.

+ (DropIODrop *) dropOperation:		(NSString*)	opString
atUrl:		(NSString*)	urlStr
withParameters:		(NSDictionary*)	params

Basic bottleneck method for Drop.io RESTful drop operations.

Builds and sends an HTTP request to the given Drop.io API URL with the HTTP method specified by opString, and an HTTP body built from the given dictionary of name/value parameter pairs. Sets lastError if an API error occurs.

Parameters:

	opString	NSString containing the HTTP request method ("GET", "POST", "PUT", or "DELETE").
	urlStr	NSString containing the Drop.io API URL to send the HTTP request to.
	params	NSDictionary containing name-value pairs to be used to construct the HTTP request body.

Returns:

DropIODrop instance returned from the API, if present, or nil.

Referenced by deleteDropNamed:withParameters:, dropWithParameters:, and updateDropNamed:withParameters:.

+ (DropIODrop *) dropWithName:

(NSString*)

aName

Creates a new drop with the given name.

Sets lastError if an API error occurs.

Parameters:

aName

NSString containing the name to give to the new drop.

Returns:

A new autoreleased DropIODrop instance returned from the API.

+ (DropIODrop *) dropWithName:		(NSString*)	aName
andPassword:		(NSString*)	aPassword

Creates a new drop with the given name and admin password.

Sets lastError if an API error occurs.

Parameters:

	aName	NSString containing the name to give to the new drop.
	aPassword	NSString containing the admin password to use for the new drop.

Returns:

A new autoreleased DropIODrop instance returned from the API.

+ (DropIODrop *) dropWithParameters:

(NSDictionary*)

params

Creates a new drop with the given parameters.

Sets lastError if an API error occurs.

Parameters:

params

NSDictionary containing name-value pairs specifying the properties of the new drop. See the Drop.io API documentation for parameter details.

Returns:

A new autoreleased DropIODrop instance returned from the API.

Referenced by dropWithName:, dropWithName:andPassword:, and dropWithRandomName.

+ (DropIODrop *) dropWithRandomName

Creates a new drop with a random name and default properties.

Sets lastError if an API error occurs.

Returns:

A new autoreleased DropIODrop instance returned from the API.

+ (DropIODrop *) findDropAtAPIURL:		(NSURL*)	dropAPIURL
error:		(NSError**)	pError

Find an existing drop given the drop.io API URL.

The pError parameter will point to an NSError object on return if any API error occurs.

Parameters:

	dropAPIURL	NSURL pointing to the Drop.io API URL for a drop.
	pError	NSError reference which will point to an NSError object on return if any error occurs. Pass nil to ignore API errors.

Returns:

An autoreleased DropIODrop object identified by the given drop URL.

Referenced by findDropNamed:withToken:error:.

+ (DropIODrop *) findDropAtDropURL:		(NSURL*)	dropURL
error:		(NSError**)	pError

Find an existing drop from a (non-API) Drop.io drop URL.

The pError parameter will point to an NSError object on return if any API error occurs.

Parameters:

	dropURL	NSURL pointing to the Drop.io web URL for a drop.
	pError	NSError reference which will point to an NSError object on return if any error occurs. Pass nil to ignore API errors.

Returns:

An autoreleased DropIODrop object identified by the given drop URL.

+ (DropIODrop *) findDropNamed:		(NSString*)	aName
error:		(NSError**)	pError

Finds an existing drop with the given name and no authentication.

The pError parameter will point to an NSError object on return if any API error occurs.

Parameters:

	aName	NSString containing the name of the drop to find.
	pError	NSError reference which will point to an NSError object on return if any error occurs. Pass nil to ignore API errors.

Returns:

An autoreleased DropIODrop object identified by the given drop name.

Referenced by findDropAtDropURL:error:.

+ (DropIODrop *) findDropNamed:		(NSString*)	aName
withToken:		(NSString*)	aToken
error:		(NSError**)	pError

Find an existing drop with the given name and security token or password.

The pError parameter will point to an NSError object on return if any API error occurs.

Parameters:

	aName	NSString containing the name of the drop to find.
	aToken	NSString containing either a security token (the DropIODrop#adminToken or DropIODrop#guestToken) previously returned from the API, or a password supplied by the user.
	pError	NSError reference which will point to an NSError object on return if any error occurs. Pass nil to ignore API errors.

Returns:

An autoreleased DropIODrop object identified by the given drop name.

Referenced by findDropNamed:error:.

+ (NSError *) lastError

Returns the last error generated from a DropKit API call.

Details about the error are contained in the userInfo property of the returned object, using the following keys:

kDropIOErrorAction

The API action that caused the error.

kDropIOErrorMessage

The error message returned from drop.io.

kDropIOErrorResult

Result of the action; usually "Success" or "Failure"

kDropIOErrorAPIURL

The drop.io URL that caused the error.

Returns:

NSError object describing the last Drop.io API error that occurred.

See also:

+ setLastError:

Referenced by setLastError:.

+ (NSArray *) parseResponse:		(NSData*)	responseData
fromNodeName:		(NSString *)	nodeName
toObject:		(NSString *)	className
parseError:		(NSError **)	error

Parses the Drop.io API response contained in the given NSData object.

Converts XML nodes with the given nodeName in the response to objects of the given className. If any error occurs, the error parameter points to an NSError object on return.

Parameters:

	responseData	NSData containing the XML response returned from a Drop.io API HTTP request.
	nodeName	NSString containing the name of target XML nodes in the returned response which are to be converted into objects.
	className	NSString containing the name of an objective-c class to instantiate from the given XML node.
	error	NSError reference which will point to an NSError object on output if any API error occurs. Pass nil to ignore API errors.

Returns:

NSArray of objects of the given className; one instance per matched XML node in the response data.

See also:

+ parseResponseFromURL:fromNodeName:toObject:parseError:

- parseXMLData:fromNodeName:toObject:parseError: (XMLToObjectParser)

Referenced by DropIODrop::assetOperation:atUrl:withParameters:, DropIODrop::docWithFilename:data:mimeType:, and dropOperation:atUrl:withParameters:.

+ (NSArray *) parseResponseFromURL:		(NSURL*)	url
fromNodeName:		(NSString *)	nodeName
toObject:		(NSString *)	className
parseError:		(NSError **)	error

Parses Drop.io API response data returned from the given URL.

Converts XML nodes with the given nodeName in the response to objects of the given className. If any error occurs, the error parameter points to an NSError object on return.

Parameters:

	url	NSURL object pointing to a Drop.io API URL.
	nodeName	NSString containing the name of target XML nodes in the returned response which are to be converted into objects.
	className	NSString containing the name of an objective-c class to instantiate from the given XML node.
	error	NSError reference which will point to an NSError object on output if any API error occurs. Pass nil to ignore API errors.

Returns:

NSArray of objects of the given className; one instance per matched XML node in the API response.

See also:

+ parseResponse:fromNodeName:toObject:parseError:

- parseXMLAtURL:fromNodeName:toObject:parseError: (XMLToObjectParser)

Referenced by findDropAtAPIURL:error:, and DropIODrop::loadAssetPages:.

+ (void) setAPIKey:

(NSString*)

aKey

Sets the Drop.io API key.

Parameters:

aKey

NSString containing the new API key value.

See also:

+ APIKey

+ checkAPIKey

+ (void) setLastError:

(NSError*)

dropioError

Sets the last DropKit error to the given NSError object.

Should not be called outside DropKit source code. Called within DropKit code when API errors occur.

Parameters:

dropioError

NSError object containing information about the last Drop.io API error.

Referenced by DropIODrop::assetOperation:atUrl:withParameters:, DropIODrop::delete, DropIOAsset::delete, DropIODrop::docWithFilename:data:mimeType:, dropOperation:atUrl:withParameters:, parseResponse:fromNodeName:toObject:parseError:, parseResponseFromURL:fromNodeName:toObject:parseError:, DropIOAsset::sendToDropNamed:, DropIOAsset::sendToEmail:message:, DropIOAsset::sendToFax:, DropIOAsset::sendWithParameters:, DropIODrop::update, and DropIOAsset::update.

+ (void) updateDropNamed:		(NSString*)	dropName
withParameters:		(NSDictionary*)	params

Updates an existing drop with the given parameters.

Sets lastError if an API error occurs.

Parameters:

	dropName	NSString containing the name of the drop to be updated.
	params	NSDictionary containing name-value pairs specifying the updated properties for the drop. See the Drop.io API documentation for parameter details.

Referenced by DropIODrop::update.

+ (NSURL *) URLForDropNamed:		(NSString*)	dropName
withToken:		(NSString*)	aToken

Returns an NSURL object pointing to the Drop.io API URL for the drop with the given name and security token.

Parameters:

	dropName	NSString containing the name of the drop.
	aToken	NSString containing the security token for the drop.

Returns:

An autoreleased NSURL object pointing to the given drop.

Referenced by DropIODrop::apiURL, and findDropNamed:withToken:error:.

---

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

• DropKit/DropIO.h
• DropKit/DropIO.m