MKNetworkOperation Class Reference
Inherits from | NSOperation |
Declared in | MKNetworkOperation.h |
Overview
@class MKNetworkOperation @abstract Represents a single unique network operation.
@discussion
You normally create an instance of this class using the methods exposed by MKNetworkEngine
Created operations are enqueued into the shared queue on MKNetworkEngine MKNetworkOperation encapsulates both request and response Printing a MKNetworkOperation prints out a cURL command that can be copied and pasted directly on terminal Freezable operations are serialized when network connectivity is lost and performed when connection is restored
Tasks
-
url
@abstract Request URL Property @property url
property -
readonlyRequest
@abstract The internal request object @property readonlyRequest
property -
readonlyResponse
@abstract The internal HTTP Response Object @property readonlyResponse
property -
readonlyPostDictionary
@abstract The internal HTTP Post data values @property readonlyPostDictionary
property -
HTTPMethod
@abstract The internal request object’s method type @property HTTPMethod
property -
HTTPStatusCode
@abstract The internal response object’s status code @property HTTPStatusCode
property -
postDataEncoding
@abstract Post Data Encoding Type Property @property postDataEncoding
property -
– setCustomPostDataEncodingHandler:forType:
@abstract Set a customized Post Data Encoding Handler for a given HTTP Content Type
-
stringEncoding
@abstract String Encoding Property @property stringEncoding
property -
freezable
@abstract Freezable request @property freezable
property -
error
@abstract Error object @property error
property -
cacheHeaders
@abstract Cache headers of the response @property cacheHeaders
property -
– setUsername:password:
@abstract Authentication methods
-
– setUsername:password:basicAuth:
@abstract Authentication methods
-
clientCertificate
@abstract Authentication methods (Client Certificate) @property clientCertificate
property -
authHandler
@abstract Custom authentication handler @property authHandler
property -
operationStateChangedHandler
@abstract Handler that you implement to monitor reachability changes @property reachabilityChangedHandler
property -
credentialPersistence
@abstract controls persistence of authentication credentials @property credentialPersistence
property -
– addHeaders:
@abstract Add additional header parameters
-
– addFile:forKey:
@abstract Attaches a file to the request
-
– addFile:forKey:mimeType:
@abstract Attaches a file to the request and allows you to specify a mime-type
-
– addData:forKey:
@abstract Attaches a resource to the request from a NSData pointer
-
– addData:forKey:mimeType:
@abstract Attaches a resource to the request from a NSData pointer and allows you to specify a mime-type
-
– onCompletion:onError:
@abstract Block Handler for completion and error
-
– onUploadProgressChanged:
@abstract Block Handler for tracking upload progress
-
– onDownloadProgressChanged:
@abstract Block Handler for tracking download progress
-
– setUploadStream:
@abstract Uploads a resource from a stream
-
– addDownloadStream:
@abstract Downloads a resource directly to a file or any output stream
-
– isCachedResponse
@abstract Helper method to check if the response is from cache
-
– responseData
@abstract Helper method to retrieve the contents
-
– responseString
@abstract Helper method to retrieve the contents as a NSString
-
– curlCommandLineString
@abstract Helper method to print the request as a cURL command
-
– responseStringWithEncoding:
@abstract Helper method to retrieve the contents as a NSString encoded using a specific string encoding
-
– responseImage
@abstract Helper method to retrieve the contents as a UIImage
-
– responseXML
-
– responseJSON
@abstract Helper method to retrieve the contents as a NSDictionary or NSArray depending on the JSON contents
-
– operationSucceeded
@abstract Overridable custom method where you can add your custom business logic error handling
-
– operationFailedWithError:
@abstract Overridable custom method where you can add your custom business logic error handling
-
– setCachedData:
-
– setCacheHandler:
-
– updateHandlersFromOperation:
-
– updateOperationBasedOnPreviousHeaders:
-
– uniqueIdentifier
-
– initWithURLString:params:httpMethod:
Properties
HTTPMethod
@abstract The internal request object’s method type @property HTTPMethod
@property (nonatomic, strong, readonly) NSString *HTTPMethod
Discussion
@abstract The internal request object’s method type @property HTTPMethod
@discussion
Returns the operation's method type
This property is readonly cannot be modified. To create an operation with a new method type, use the operationWithURLString:params:httpMethod:
Declared In
MKNetworkOperation.h
HTTPStatusCode
@abstract The internal response object’s status code @property HTTPStatusCode
@property (nonatomic, assign, readonly) NSInteger HTTPStatusCode
Discussion
@abstract The internal response object’s status code @property HTTPStatusCode
@discussion
Returns the operation's response's status code.
Returns 0 when the operation has not yet started and the response is not available. This property is readonly cannot be modified.
Declared In
MKNetworkOperation.h
authHandler
@abstract Custom authentication handler @property authHandler
@property (nonatomic, copy) MKNKAuthBlock authHandler
Discussion
@abstract Custom authentication handler @property authHandler
@discussion
If your request needs to be authenticated using a custom method (like a Web page/HTML Form), add a block method here
and process the NSURLAuthenticationChallenge
Declared In
MKNetworkOperation.h
cacheHeaders
@abstract Cache headers of the response @property cacheHeaders
@property (strong, nonatomic) NSMutableDictionary *cacheHeaders
Discussion
@abstract Cache headers of the response @property cacheHeaders
@discussion
If the network operation is a GET, this dictionary will be populated with relevant cache related headers
MKNetworkKit assumes a 7 day cache for images and 1 minute cache for all requests with no-cache set
This property is internal to MKNetworkKit. Modifying this is not recommended and will result in unexpected behaviour
Declared In
MKNetworkOperation.h
clientCertificate
@abstract Authentication methods (Client Certificate) @property clientCertificate
@property (strong, nonatomic) NSString *clientCertificate
Discussion
@abstract Authentication methods (Client Certificate) @property clientCertificate
@discussion
If your request needs to be authenticated using a client certificate, set the certificate path here
Declared In
MKNetworkOperation.h
credentialPersistence
@abstract controls persistence of authentication credentials @property credentialPersistence
@property (nonatomic, assign) NSURLCredentialPersistence credentialPersistence
Discussion
@abstract controls persistence of authentication credentials @property credentialPersistence
@discussion The default value is set to NSURLCredentialPersistenceForSession, change it to NSURLCredentialPersistenceNone to avoid caching issues (isse #35)
Declared In
MKNetworkOperation.h
error
@abstract Error object @property error
@property (nonatomic, readonly, strong) NSError *error
Discussion
@abstract Error object @property error
@discussion
If the network operation results in an error, this will hold the response error, otherwise it will be nil
Declared In
MKNetworkOperation.h
freezable
@abstract Freezable request @property freezable
@property (nonatomic, assign) BOOL freezable
Discussion
@abstract Freezable request @property freezable
@discussion
Freezable operations are serialized when the network goes down and restored when the connectivity is up again.
Only POST, PUT and DELETE operations are freezable. In short, any operation that changes the state of the server are freezable, creating a tweet, checking into a new location etc., Operations like fetching a list of tweets (think readonly GET operations) are not freezable. MKNetworkKit doesn’t freeze (readonly) GET operations even if they are marked as freezable
Declared In
MKNetworkOperation.h
operationStateChangedHandler
@abstract Handler that you implement to monitor reachability changes @property reachabilityChangedHandler
@property (copy, nonatomic) void ( ^ ) ( MKNetworkOperationState newState ) operationStateChangedHandler
Discussion
@abstract Handler that you implement to monitor reachability changes @property reachabilityChangedHandler
@discussion
The framework calls this handler whenever the reachability of the host changes.
The default implementation freezes the queued operations and stops network activity You normally don’t have to implement this unless you need to show a HUD notifying the user of connectivity loss
Declared In
MKNetworkOperation.h
postDataEncoding
@abstract Post Data Encoding Type Property @property postDataEncoding
@property (nonatomic, assign) MKNKPostDataEncodingType postDataEncoding
Discussion
@abstract Post Data Encoding Type Property @property postDataEncoding
@discussion Specifies which type of encoding should be used to encode post data. MKNKPostDataEncodingTypeURL is the default which defaults to application/x-www-form-urlencoded MKNKPostDataEncodingTypeJSON uses JSON encoding. JSON Encoding is supported only in iOS 5 or Mac OS X 10.7 and above. On older operating systems, JSON Encoding reverts back to URL Encoding You can use the postDataEncodingHandler to provide a custom postDataEncoding For example, JSON encoding using a third party library.
Declared In
MKNetworkOperation.h
readonlyPostDictionary
@abstract The internal HTTP Post data values @property readonlyPostDictionary
@property (nonatomic, strong, readonly) NSDictionary *readonlyPostDictionary
Discussion
@abstract The internal HTTP Post data values @property readonlyPostDictionary
@discussion
Returns the operation's post data dictionary
This property is readonly cannot be updated. Rather, updating this post dictionary doesn’t have any effect on the MKNetworkOperation. Use the addHeaders method to add post data parameters to the operation.
@seealso addHeaders:
Declared In
MKNetworkOperation.h
readonlyRequest
@abstract The internal request object @property readonlyRequest
@property (nonatomic, strong, readonly) NSURLRequest *readonlyRequest
Discussion
@abstract The internal request object @property readonlyRequest
@discussion
Returns the operation's actual request object
This property is readonly cannot be modified. To create an operation with a new request, use the operationWithURLString:params:httpMethod:
Declared In
MKNetworkOperation.h
readonlyResponse
@abstract The internal HTTP Response Object @property readonlyResponse
@property (nonatomic, strong, readonly) NSHTTPURLResponse *readonlyResponse
Discussion
@abstract The internal HTTP Response Object @property readonlyResponse
@discussion
Returns the operation's actual response object
This property is readonly cannot be updated.
Declared In
MKNetworkOperation.h
stringEncoding
@abstract String Encoding Property @property stringEncoding
@property (nonatomic, assign) NSStringEncoding stringEncoding
Discussion
@abstract String Encoding Property @property stringEncoding
@discussion Specifies which type of encoding should be used to encode URL strings
Declared In
MKNetworkOperation.h
url
@abstract Request URL Property @property url
@property (nonatomic, readonly) NSString *url
Discussion
@abstract Request URL Property @property url
@discussion
Returns the operation's URL
This property is readonly cannot be updated. To create an operation with a specific URL, use the operationWithURLString:params:httpMethod:
Declared In
MKNetworkOperation.h
Instance Methods
addData:forKey:
@abstract Attaches a resource to the request from a NSData pointer
- (void)addData:(NSData *)data forKey:(NSString *)key
Discussion
@abstract Attaches a resource to the request from a NSData pointer
@discussion
This method lets you attach a NSData object to the request. The behaviour is exactly similar to addFile:forKey:
The method has a side effect. It changes the HTTPMethod to “POST” regardless of what it was before. It also changes the post format to multipart/form-data The mime-type is assumed to be application/octet-stream
Declared In
MKNetworkOperation.h
addData:forKey:mimeType:
@abstract Attaches a resource to the request from a NSData pointer and allows you to specify a mime-type
- (void)addData:(NSData *)data forKey:(NSString *)key mimeType:(NSString *)mimeType
Discussion
@abstract Attaches a resource to the request from a NSData pointer and allows you to specify a mime-type
@discussion
This method lets you attach a NSData object to the request. The behaviour is exactly similar to addFile:forKey:mimeType:
The method has a side effect. It changes the HTTPMethod to “POST” regardless of what it was before. It also changes the post format to multipart/form-data
Declared In
MKNetworkOperation.h
addDownloadStream:
@abstract Downloads a resource directly to a file or any output stream
- (void)addDownloadStream:(NSOutputStream *)outputStream
Discussion
@abstract Downloads a resource directly to a file or any output stream
@discussion
This method can be used to download a resource directly to a stream (It's normally a file in most cases).
Calling this method multiple times adds new streams to the same operation. A stream cannot be removed after it is added.
Declared In
MKNetworkOperation.h
addFile:forKey:
@abstract Attaches a file to the request
- (void)addFile:(NSString *)filePath forKey:(NSString *)key
Discussion
@abstract Attaches a file to the request
@discussion
This method lets you attach a file to the request
The method has a side effect. It changes the HTTPMethod to “POST” regardless of what it was before. It also changes the post format to multipart/form-data The mime-type is assumed to be application/octet-stream
Declared In
MKNetworkOperation.h
addFile:forKey:mimeType:
@abstract Attaches a file to the request and allows you to specify a mime-type
- (void)addFile:(NSString *)filePath forKey:(NSString *)key mimeType:(NSString *)mimeType
Discussion
@abstract Attaches a file to the request and allows you to specify a mime-type
@discussion
This method lets you attach a file to the request
The method has a side effect. It changes the HTTPMethod to “POST” regardless of what it was before. It also changes the post format to multipart/form-data
Declared In
MKNetworkOperation.h
addHeaders:
@abstract Add additional header parameters
- (void)addHeaders:(NSDictionary *)headersDictionary
Discussion
@abstract Add additional header parameters
@discussion
If you ever need to set additional headers after creating your operation, you this method.
You normally set default headers to the engine and they get added to every request you create. On specific cases where you need to set a new header parameter for just a single API call, you can use this
Declared In
MKNetworkOperation.h
curlCommandLineString
@abstract Helper method to print the request as a cURL command
- (NSString *)curlCommandLineString
Discussion
@abstract Helper method to print the request as a cURL command
@discussion
This method is used for displaying the request you created as a cURL command
Declared In
MKNetworkOperation.h
initWithURLString:params:httpMethod:
- (id)initWithURLString:(NSString *)aURLString params:(NSMutableDictionary *)params httpMethod:(NSString *)method
isCachedResponse
@abstract Helper method to check if the response is from cache
- (BOOL)isCachedResponse
Discussion
@abstract Helper method to check if the response is from cache
@discussion
This method should be used to check if your response is cached.
When you enable caching on MKNetworkEngine, your completionHandler will be called with cached data first and then with real data, later after fetching. In your handler, you can call this method to check if it is from cache or not
Declared In
MKNetworkOperation.h
onCompletion:onError:
@abstract Block Handler for completion and error
- (void)onCompletion:(MKNKResponseBlock)response onError:(MKNKErrorBlock)error
Discussion
@abstract Block Handler for completion and error
@discussion
This method sets your completion and error blocks. If your operation's response data was previously called,
the completion block will be called almost immediately with the cached response. You can check if the completion handler was invoked with a cached data or with real data by calling the isCachedResponse method.
@seealso isCachedResponse
Declared In
MKNetworkOperation.h
onDownloadProgressChanged:
@abstract Block Handler for tracking download progress
- (void)onDownloadProgressChanged:(MKNKProgressBlock)downloadProgressBlock
Discussion
@abstract Block Handler for tracking download progress
@discussion
This method can be used to update your progress bars when a download is in progress.
The value range of the progress is 0 to 1.
Declared In
MKNetworkOperation.h
onUploadProgressChanged:
@abstract Block Handler for tracking upload progress
- (void)onUploadProgressChanged:(MKNKProgressBlock)uploadProgressBlock
Discussion
@abstract Block Handler for tracking upload progress
@discussion
This method can be used to update your progress bars when an upload is in progress.
The value range of the progress is 0 to 1.
Declared In
MKNetworkOperation.h
operationFailedWithError:
@abstract Overridable custom method where you can add your custom business logic error handling
- (void)operationFailedWithError:(NSError *)error
Discussion
@abstract Overridable custom method where you can add your custom business logic error handling
@discussion
This optional method can be overridden to do custom error handling. Be sure to call [super operationSucceeded] at the last.
For example, a invalid HTTP response (401) like “Unauthorized” might be a valid case in your app. You can override this method and called [super operationSucceeded]; to notify that HTTP call failed but the method ended as a success call. For example, Facebook login failed, but to your business implementation, it’s not a problem as you are going to try alternative login mechanisms.
Declared In
MKNetworkOperation.h
operationSucceeded
@abstract Overridable custom method where you can add your custom business logic error handling
- (void)operationSucceeded
Discussion
@abstract Overridable custom method where you can add your custom business logic error handling
@discussion
This optional method can be overridden to do custom error handling. Be sure to call [super operationSucceeded] at the last.
For example, a valid HTTP response (200) like “Item not found in database” might have a custom business error code You can override this method and called [super failWithError:customError]; to notify that HTTP call was successful but the method ended as a failed call
Declared In
MKNetworkOperation.h
responseData
@abstract Helper method to retrieve the contents
- (NSData *)responseData
Discussion
@abstract Helper method to retrieve the contents
@discussion
This method is used for accessing the downloaded data. If the operation is still in progress, the method returns nil instead of partial data. To access partial data, use a downloadStream.
@seealso addDownloadStream:
Declared In
MKNetworkOperation.h
responseImage
@abstract Helper method to retrieve the contents as a UIImage
- (UIImage *)responseImage
Discussion
@abstract Helper method to retrieve the contents as a UIImage
@discussion
This method is used for accessing the downloaded data as a UIImage. If the operation is still in progress, the method returns nil instead of a partial image. To access partial data, use a downloadStream. If the response is not a valid image, this method returns nil. This method doesn't obey the response mime type property. If the server response with a proper image data but set the mime type incorrectly, this method will still be able access the response as an image.
@seealso addDownloadStream:
Declared In
MKNetworkOperation.h
responseJSON
@abstract Helper method to retrieve the contents as a NSDictionary or NSArray depending on the JSON contents
- (id)responseJSON
Discussion
@abstract Helper method to retrieve the contents as a NSDictionary or NSArray depending on the JSON contents
@discussion
This method is used for accessing the downloaded data as a NSDictionary or an NSArray. If the operation is still in progress, the method returns nil. If the response is not a valid JSON, this method returns nil.
@availability iOS 5 and above or Mac OS 10.7 and above
Declared In
MKNetworkOperation.h
responseString
@abstract Helper method to retrieve the contents as a NSString
- (NSString *)responseString
Discussion
@abstract Helper method to retrieve the contents as a NSString
@discussion
This method is used for accessing the downloaded data. If the operation is still in progress, the method returns nil instead of partial data. To access partial data, use a downloadStream. The method also converts the responseData to a NSString using the stringEncoding specified in the operation
@seealso addDownloadStream: stringEncoding
Declared In
MKNetworkOperation.h
responseStringWithEncoding:
@abstract Helper method to retrieve the contents as a NSString encoded using a specific string encoding
- (NSString *)responseStringWithEncoding:(NSStringEncoding)encoding
Discussion
@abstract Helper method to retrieve the contents as a NSString encoded using a specific string encoding
@discussion
This method is used for accessing the downloaded data. If the operation is still in progress, the method returns nil instead of partial data. To access partial data, use a downloadStream. The method also converts the responseData to a NSString using the stringEncoding specified in the parameter
@seealso addDownloadStream: stringEncoding
Declared In
MKNetworkOperation.h
setCustomPostDataEncodingHandler:forType:
@abstract Set a customized Post Data Encoding Handler for a given HTTP Content Type
- (void)setCustomPostDataEncodingHandler:(MKNKEncodingBlock)postDataEncodingHandler forType:(NSString *)contentType
Discussion
@abstract Set a customized Post Data Encoding Handler for a given HTTP Content Type
@discussion If you need customized post data encoding support, provide a block method here. This block method will be invoked only when your HTTP Method is POST or PUT For default URL encoding or JSON encoding, use the property postDataEncoding If you change the postData format, it’s your responsiblity to provide a correct Content-Type.
@seealso postDataEncoding
Declared In
MKNetworkOperation.h
setUploadStream:
@abstract Uploads a resource from a stream
- (void)setUploadStream:(NSInputStream *)inputStream
Discussion
@abstract Uploads a resource from a stream
@discussion
This method can be used to upload a resource for a post body directly from a stream.
Declared In
MKNetworkOperation.h
setUsername:password:
@abstract Authentication methods
- (void)setUsername:(NSString *)name password:(NSString *)password
Discussion
@abstract Authentication methods
@discussion
If your request needs to be authenticated, set your username and password using this method.
Declared In
MKNetworkOperation.h
setUsername:password:basicAuth:
@abstract Authentication methods
- (void)setUsername:(NSString *)username password:(NSString *)password basicAuth:(BOOL)bYesOrNo
Discussion
@abstract Authentication methods
@discussion
If your request needs to be authenticated using HTTP Basic, use this method to set your username and password.
Calling this method with basicAuth:NO is same as calling setUserName:password: @seealso setUserName:password:
Declared In
MKNetworkOperation.h