ArcGIS Runtime SDK for iOS: AGSRequestOperation Class Reference
ArcGIS Runtime SDK for iOS  100.15
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:
AGSObservableOperation <AGSCancelable> AGSOperationBase <AGSOperation> AGSJSONRequestOperation

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
 
AGSCredentialcredential
 
NSError * error
 
void(^ internalCompletion )(void)
 
id< AGSLoadableloadDependency
 
AGSRequestHTTPMethod method
 
NSURL * outputFileURL
 
NSProgress * progress
 
void(^ progressHandler )(long long totalBytesDownloaded, long long totalBytesExpected)
 
NSDictionary< NSString *, id > * queryParameters
 
id< AGSRemoteResourceremoteResource
 
NSURLRequest * request
 
AGSRequestConfigurationrequestConfiguration
 
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
remoteResourceThe 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.
requestRequest 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
remoteResourceThe 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.
URLURL to initialize the request operation.
queryParametersQuery 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
remoteResourceThe 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.
URLURL to initialize the request operation.
queryParametersQuery parameters to submit along with the request.
methodThe 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
urlURL 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
listenerThe listener to add the completion block for.
completionThe 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
listenerThe 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