AGSRequestOperation Class Reference

Description

Base class for operations that perform http requests.

The request will execute on a background thread. Once the response has been parsed the completion blocks will called.

• This class encapsulates the logic for accessing secured (token or basic) resources. Including refreshing a token if it has expired. It also has the ability to perform the parsing of the response in a child operation so that the main thread of the application is not bogged down.

• This class, or a subclass thereof, is used by all the tasks execute requests across the wire.

• This class, or a subclass thereof, is also used by most of the layers for retrieving images or tiles.

• This class can be used directly, but you will probably use a subclass of it for getting back the response data in the format that you are looking for.

Since

100

Inheritance diagram for AGSRequestOperation:

Instance Methods
(void)	- cancel
(void)	- cancel
(void)	- didComplete:
(void)	- doCancel
(void)	- doExecute
(void)	- doneExecuting
(void)	- execute
(instancetype)	- initWithRemoteResource:request:
(instancetype)	- initWithRemoteResource:URL:queryParameters:
(instancetype)	- initWithRemoteResource:URL:queryParameters:method:
(instancetype)	- initWithURL:
(BOOL)	- isCanceled
(BOOL)	- isPaused
(BOOL)	- isRegisteredListener:
(BOOL)	- pause
(void)	- registerListener:forCompletion:
(void)	- resume
(void)	- unregisterListener:

Properties
BOOL	canceled
BOOL	cancelSessionWhenOperationIsCanceled
AGSCredential *	credential
NSError *	error
void(^	internalCompletion )(void)
id< AGSLoadable >	loadDependency
AGSRequestHTTPMethod	method
NSURL *	outputFileURL
NSProgress *	progress
void(^	progressHandler )(long long totalBytesDownloaded, long long totalBytesExpected)
NSDictionary< NSString *, id > *	queryParameters
id< AGSRemoteResource >	remoteResource
NSURLRequest *	request
AGSRequestConfiguration *	requestConfiguration
NSURLResponse *	response
id	result
NSString *	sessionID
BOOL	startAsynchronously
AGSOperationState	state
long long	totalBytesDownloaded
long long	totalBytesExpected
NSURL *	URL

Method Documentation

cancel [1/2]

- (void) cancel

requiredinherited

Cancel the operation

Since

100

cancel [2/2]

- (void) cancel

Cancels the operation.

Since

100

didComplete:

- (void) didComplete:

(BOOL)

everStarted

Subclasses should override if they want to run some code once the operation is completed. This function is guaranteed to only be called once. everStarted will be NO if the operation was canceled before it could be started.

Since

100

Provided by category AGSOperationBase(ForSubclassEyesOnly).

doCancel

- (void) doCancel

Subclasses can override to do the actual work to cancel the operation. Once cancel is complete, call doneExecuting. For operations that do not do all of their work in doExecute, it makes sense to override this and cancel any network connections, etc. Then when the cancel is complete, you call doneExecuting. For operations where the work is all done in doExecute they shouldn't need to override this, you should just check the isCanceled property throughout the execution of the operation and if it is canceled then call doneExecuting and return.

Since

100

Provided by category AGSOperationBase(ForSubclassEyesOnly).

doExecute

- (void) doExecute

Subclasses should override to do the actual execution of the operation. Once done, call doneExecuting.

Since

100

Provided by category AGSOperationBase(ForSubclassEyesOnly).

doneExecuting

- (void) doneExecuting

Subclasses should call this when they are done executing or done cancelling.

Since

100

Provided by category AGSOperationBase(ForSubclassEyesOnly).

execute

- (void) execute

Starts the operation

Since

100

initWithRemoteResource:request:

- (instancetype) initWithRemoteResource:		(nullable id< AGSRemoteResource >)	remoteResource
request:		(NSURLRequest *)	NS_DESIGNATED_INITIALIZER

Initialize an AGSRequestOperation with the specified request.

Parameters

remoteResource	The AGSRemoteResource which is responsible for making the request. When the remoteResource is set, properties will get pulled from that such as the credential, requestConfiguration, etc.
request	Request to initialize the operation with.

Returns

Initialized AGSRequestOperation.

Since

100

initWithRemoteResource:URL:queryParameters:

- (instancetype) initWithRemoteResource:		(nullable id< AGSRemoteResource >)	remoteResource
URL:		(NSURL *)	URL
queryParameters:		(nullable NSDictionary< NSString *, id > *)	queryParameters

Initialize an AGSRequestOperation with the specified remote resource, url and query parameters.

Parameters

remoteResource	The AGSRemoteResource which is responsible for making the request. When the remoteResource is set, properties will get pulled from that such as the credential, requestConfiguration, etc.
URL	URL to initialize the request operation.
queryParameters	Query parameters to submit along with the request.

Returns

Initialized AGSRequestOperation.

Since

100

initWithRemoteResource:URL:queryParameters:method:

- (instancetype) initWithRemoteResource:		(nullable id< AGSRemoteResource >)	remoteResource
URL:		(NSURL *)	URL
queryParameters:		(nullable NSDictionary< NSString *, id > *)	queryParameters
method:		(AGSRequestHTTPMethod)	NS_DESIGNATED_INITIALIZER

Initialize an AGSRequestOperation with the specified remote resource, url, query parameters and HTTP method.

Parameters

remoteResource	The AGSRemoteResource which is responsible for making the request. When the remoteResource is set, properties will get pulled from that such as the credential, requestConfiguration, etc.
URL	URL to initialize the request operation.
queryParameters	Query parameters to submit along with the request.
method	The AGSRequestHTTPMethod to be used with this request.

Returns

Initialized AGSRequestOperation.

Since

100

initWithURL:

- (instancetype) initWithURL:

(NSURL *)

url

Initialize an AGSRequestOperation with the specified url.

Parameters

url	URL to initialize the request operation.

Returns

Initialized AGSRequestOperation.

Since

100

isCanceled

- (BOOL) isCanceled

requiredinherited

Indicates whether the operation has been canceled

Since

100

isPaused

- (BOOL) isPaused

Indicates whether the operation is paused.

Since

100

Deprecated:

100.1. Please use the isPaused property through the NSProgress API (exposed via NSProgressReporting through the progress property).

isRegisteredListener:

- (BOOL) isRegisteredListener:

(id)

listener

Returns whether or not the specified object is a registered as a listener to this operation.

Since

100

pause

- (BOOL) pause

Pause the operation. Returns YES if it isPaused is YES after calling this. If the operation is in a state where it cannot be paused, it will return NO. For example if the operation is canceled or done.

Since

100

Deprecated:

100.1. Please use the pause method through the NSProgress API (exposed via NSProgressReporting through the progress property).

registerListener:forCompletion:

- (void) registerListener:		(id)	listener
forCompletion:		(void(^)(id __nullable result, NSError *__nullable error))	completion

Adds a completion handler to the operation for the specified listener. If you are using this option, you can unregister a completionHandler for a listener if you need to. When there are no more listeners the operation will be canceled automatically.

Parameters

listener	The listener to add the completion block for.
completion	The completion handler to be called.

Since

100

resume

- (void) resume

Resumes an operation after it's been paused. Only valid to be called when isPaused is YES.

Since

100

Deprecated:

100.1. Please use the resume method through the NSProgress API (exposed via NSProgressReporting through the progress property).

unregisterListener:

- (void) unregisterListener:

(id)

listener

Removes the registered completion handler to the operation for the specified listener. When there are no more listeners the operation will be canceled automatically. To avoid any potential retain cycles the listener is not retained by the operation. Unregistering is just the way to tell the operation that you no longer care about getting the completion event.

Parameters

listener

The listener to unregister

Since

100

Property Documentation

canceled

- (BOOL) canceled

readnonatomicassigninherited

Whether or not cancel has been called on the operation. "Canceled" is a modifier on the current state since:

1. The operation can be still "executing" until the cancel takes effect.
2. An operation can be canceled and in a completed state at the same time.

   Since

   100

cancelSessionWhenOperationIsCanceled

- (BOOL) cancelSessionWhenOperationIsCanceled

readwritenonatomicassign

Defaults to YES. Specifies whether or not the download session used to download the file is canceled when the operation is canceled. Otherwise the session stays in the state that it was in. The value of occasionally being able to set this to NO is that you can cancel the operation, which is taking the spot in the queue and have the download continue out of process, or remain paused, if you wish.

Since

100

credential

- (AGSCredential*) credential

readwritenonatomicstrong

Security credentials to access the remote resource. Only applicable if the resource is secured.

Since

100

error

- (NSError*) error

readnonatomicstronginherited

The error, if any, that occurred.

Since

100

internalCompletion

- (void(^ internalCompletion) (void))

readwritenonatomiccopyinherited

The block the operation will call to signify to the operation queue that the operation is complete. This block is reserved for use by the AGSOperationQueue. Do not assign your own block to this.

Since

100

loadDependency

- (id<AGSLoadable>) loadDependency

readwritenonatomicweak

The id<AGSLoadable> object that should be loaded before this request is kicked off.

Since

100

method

- (AGSRequestHTTPMethod) method

readwritenonatomicassign

Flag to determine whether or not the request is a GET or a POST and if it is a post how it's parameters are encoded.

Since

100

outputFileURL

- (NSURL*) outputFileURL

readwritenonatomicstrong

If this is set then the data is saved to this file as it is retrieved. Must be set to a local file URL.

Since

100

progress

- (NSProgress*) progress

readnonatomicstrong

The progress for this operation. As a consumer of this progress property, you can observe it's property changes and pause, cancel, resume. Do not, however, set the readwrite properties of this progress object. Those are reserved for internal use. Setting them externally will corrupt the state and lead to undefined behavior.

Since

100.1

progressHandler

- (void(^ progressHandler) (long long totalBytesDownloaded, long long totalBytesExpected))

readwritenonatomiccopy

If provided, the operation will call this block with the progress of the request. If the content length is unknown or not specified in the request, totalBytesExpected will return -1.

Since

100

queryParameters

- (NSDictionary<NSString*,id>*) queryParameters

readatomiccopy

Query parameters to be used in the request to URL.

Since

100

remoteResource

- (id<AGSRemoteResource>) remoteResource

readnonatomicweak

The remote resource, if applicable, that is making the web request.

Since

100

request

- (NSURLRequest*) request

readnonatomicstrong

Request object to be used instead of generating one on the fly.

Since

100

requestConfiguration

- (AGSRequestConfiguration*) requestConfiguration

readwritenonatomicstrong

The AGSRequestConfiguration object which defines the behavior and policies to use when accessing the remote resource. Defaults to the [AGSRequestConfiguration globalConfiguration]

Since

100

response

- (NSURLResponse*) response

readnonatomicstrong

The response of the request.

Since

100

result

- (id) result

readnonatomicstronginherited

The results of an operation. It will be of type NSDictionary when the result is json, AGSImage when the result is an image, and NSData when anything else.

Since

100

sessionID

- (NSString*) sessionID

readwritenonatomiccopy

If provided, the operation will use NSURLSession to allow for downloading in the background. This requires that outputFileURL is also specified.

Since

100

startAsynchronously

- (BOOL) startAsynchronously

readwritenonatomicassigninherited

Subclasses can set this if they want to be started asynchronously or not. If an operation does most or all of it's work in doExecute it should set this to YES. If an operation returns quickly from doExecute and does all of it's work on a different queue then this value should be NO. The default value is YES.

Provided by category AGSOperationBase(ForSubclassEyesOnly).

state

- (AGSOperationState) state

readnonatomicassigninherited

The current state of the operation.

Since

100

totalBytesDownloaded

- (long long) totalBytesDownloaded

readnonatomicassign

The number of bytes currently downloaded for this request.

Since

100

totalBytesExpected

- (long long) totalBytesExpected

readnonatomicassign

The total number of bytes expected to be downloaded. Will be -1 if unknown.

Since

100

URL

- (NSURL*) URL

readnonatomicstrong

URL of the resource to make a request from.

Since

100