Merge pull request #9 from hansemannn/support-upload

[MOD-2328] Support upload-tasks, move session and configuration to own proxy, major refactoring

Author: hansemannn

.travis.yml

@@ -1,5 +1,5 @@
 language: objective-c
-osx_image: xcode7.1
+osx_image: xcode8.2
 env:
  global:
     - "MODULE_NAME=ti.urlsession" 
@@ -8,7 +8,7 @@ before_install:
 install:
     - cd $MODULE_ROOT
     - curl -o install.sh https://raw.githubusercontent.com/appcelerator-modules/ci/master/travis/install.sh
-    - source install.sh -s "--branch 5_1_X"
+    - source install.sh -s "--branch 6_0_X"
 script:
     - curl -o script.sh https://raw.githubusercontent.com/appcelerator-modules/ci/master/travis/script.sh    
     - source script.sh
@@ -27,4 +27,4 @@ deploy:
   skip_cleanup: true
   on:
     repo: appcelerator-modules/ti.urlsession
-    branch: master
+    branch: master

apidoc/Session.yml

@@ -0,0 +1,130 @@
+---
+name: Modules.URLSession.Session
+summary: The session object used to start new tasks.
+description: |
+    These APIs are supported on iOS 7 and later.
+
+    The NSURLSession class and related classes provide an API for downloading content. 
+    This API provides a rich set of delegate methods for supporting authentication and gives 
+    your app the ability to perform background downloads when your app is not running or, in iOS, 
+    while your app is suspended.
+
+    [iOS Background Services guide](http://docs.appcelerator.com/titanium/latest/#!/guide/iOS_Background_Services).
+
+extends: Titanium.Module
+osver: {ios: {min: "7.0"}}
+platforms: [iphone, ipad]
+since: 6.1.0
+
+methods:
+  - name: finishTasksAndInvalidate
+    summary: Invalidates the given session object, allowing any outstanding tasks to finish.
+    description: |
+        This method returns immediately without waiting for tasks to finish. Once a session is invalidated,
+        new tasks cannot be created in the session, but existing tasks continue until completion. Once
+        invalidated, references to the events and callback objects are broken. Session objects cannot be
+        reused. To cancel all outstanding tasks, call `invalidateAndCancel` instead.
+
+  - name: invalidateAndCancel
+    summary: Cancels all outstanding tasks and then invalidates the session object.
+    description: |
+        Once invalidated, references to the events and callback objects are broken. 
+        Session objects cannot be reused. To allow outstanding tasks to run until 
+        completion, call `finishTasksAndInvalidate` instead.
+         
+ - name: downloadTask
+   summary: |
+       Creates a download task for the specified URL, within the provided session 
+       object and saves the results to a file.
+   description: |
+       Once this function is called, the download starts automatically. The progress 
+       of the download can be monitored by listening to the `downloadprogress`, 
+       `downloadcompleted`, `sessioneventscompleted` and `sessioncompleted` events.
+   parameters:
+     - name: args
+       summary: An object representing the arguments to add a new background task.
+       type: DownloadTaskType
+   returns:
+       summary: Task's identifier number.
+       type: String    
+ 
+  - name: uploadTask
+    summary: |
+        Creates a upload task for the specified URL, within the provided session 
+        object and local data.
+    description: |
+        Once this function is called, the upload starts automatically. The progress 
+        of the upload can be monitored by listening to the `uploadprogress` and 
+        `sessioncompleted` events.
+    parameters:
+      - name: args
+        summary: An object representing the arguments to add a new upload task.
+        type: UploadTaskType
+    returns:
+        summary: Task's identifier number.
+        type: String          
+
+  - name: reset
+    summary: Empties all cookies, cache and credential stores, removes disk files, calls <Modules.URLSession.Session.flush>.
+    parameters:
+      - name: callback
+        summary: Callback to be invoked when the reset completes.
+        type: Callback
+
+  - name: flush
+    summary: Flushes storage to disk and clear transient network caches.
+    parameters:
+      - name: callback
+        summary: Callback to be invoked when the reset completes.
+        type: Callback
+
+properties:
+  - name: configuration
+    summary: The configuration used for this url session.
+    description: |
+        Configuration options for an <Modules.URLSession.Session> object.  
+        When a session is created, a copy of the configuration object is made.
+        you cannot modify the configuration of a session after it has been created.
+     
+        The shared session uses the global singleton credential, cache
+        and cookie storage objects.
+     
+        An ephemeral session has no persistent disk storage for cookies,
+        cache or credentials.
+     
+        A background session can be used to perform networking operations
+       on behalf of a suspended application, within certain constraints.
+    optional: false
+    availability: creation
+    type: Modules.URLSession.SessionConfiguration
+
+---
+name: DownloadTaskType
+summary: The parameter for [downloadTask](Modules.URLSession.Session.downloadTask) method.
+properties:
+  - name: url
+    summary: The remote url used for this data task.
+    type: String
+
+---
+name: UploadTaskType
+summary: The parameter for [uploadTask](Modules.URLSession.Session.uploadTask) method.
+properties:
+  - name: url
+    summary: The remote url used for this data task.
+    type: String
+    optional: false
+
+  - name: data
+    summary: The data blob used for this data task.
+    type: Titanium.Blob
+    optional: false
+
+  - name: method
+    summary: The request method (e.g. POST or PUT)
+    default: POST
+    type: String
+
+  - name: requestHeaders
+    summary: Additional request headers to pass to the request.
+    type: String

apidoc/SessionConfiguration.yml

@@ -0,0 +1,28 @@
+---
+name: Modules.URLSession.SessionConfiguration
+summary: The session configuration object used to create new url sessions.
+description: |
+    These APIs are supported on iOS 7 and later.
+
+    An NSURLSessionConfiguration object defines the behavior and policies to use 
+    when uploading and downloading data using an URLSession object. When uploading 
+    or downloading data, creating a configuration object is always the first step 
+    you must take. You use this object to configure the timeout values, caching 
+    policies, connection requirements, and other types of information that you 
+    intend to use with your URLSession object.
+
+    [iOS Background Services guide](http://docs.appcelerator.com/titanium/latest/#!/guide/iOS_Background_Services).
+
+extends: Titanium.Module
+osver: {ios: {min: "7.0"}}
+platforms: [iphone, ipad]
+since: 6.1.0
+
+properties:
+  - name: identifier
+    summary: The unique identifier for the configuration object.
+    description: |
+        This parameter must not be non-null or an empty string.
+    optional: false
+    availability: creation
+    type: String

apidoc/urlsession.yml

@@ -34,35 +34,6 @@ excludes:
     properties: [bubbleParent]
 
 methods:
-  - name: createURLSessionBackgroundConfiguration
-    summary: |
-        Creates a preconfigured session configuration object that can be used to create a URL session for
-        performing a background download task.
-    parameters:
-      - name: indentifier
-        summary: Arbitrary string used to identify the session in the events.
-        type: String
-    returns:
-        summary: Configuration object to pass to the <Modules.URLSession.createURLSession> method.
-        type: Object
-
-  - name: createURLSession
-    summary: Creates a session with the specified session configuration.
-    description: |
-        If the session configuration was created with the identifier of a existing session,
-        then this function would return the pre-existing session.
-
-        The session object keeps a strong reference until your app explicitly invalidates the
-        session. If you do not invalidate the session by calling the `invalidateAndCancel` or
-         `finishTasksAndInvalidate` method, your app leaks memory.
-    parameters:
-      - name: sessionConfiguration
-        summary: Session configuration object created with the <Modules.URLSession.createURLSessionBackgroundConfiguration>
-        type: Object 
-    returns:
-        summary: URL session object.
-        type: Object
-
   - name: finishTasksAndInvalidate
     summary: Invalidates the given session object, allowing any outstanding tasks to finish.
     description: |
@@ -74,6 +45,9 @@ methods:
       - name: session
         summary: URL session object.
         type: Object
+    deprecated:
+        since: 6.1.0
+        notes: Use <Modules.URLSession.Session.finishTasksAndInvalidate> (on the session object) instead.
 
   - name: invalidateAndCancel
     summary: Cancels all outstanding tasks and then invalidates the session object.
@@ -85,8 +59,14 @@ methods:
       - name: session
         summary: URL session object.
         type: Object
+    deprecated:
+        since: 6.1.0
+        notes: Use <Modules.URLSession.Session.invalidateAndCancel> (on the session object) instead.
 
   - name: backgroundDownloadTaskWithURL
+    deprecated:
+        since: 6.1.0
+        notes: Use <Modules.URLSession.Session.downloadTask> on the session directly.
     summary: |
         Creates a download task for the specified URL, within the provided session object and saves the
         results to a file.
@@ -104,3 +84,23 @@ methods:
     returns:
         summary: Task's identifier number.
         type: String    
+ 
+properties:
+  - name: configuration
+    summary: The configuration used for this url session.
+    description: |
+        Configuration options for an <Modules.URLSession.Session> object.  
+        When a session is created, a copy of the configuration object is made.
+        you cannot modify the configuration of a session after it has been created.
+     
+        The shared session uses the global singleton credential, cache
+        and cookie storage objects.
+     
+        An ephemeral session has no persistent disk storage for cookies,
+        cache or credentials.
+     
+        A background session can be used to perform networking operations
+       on behalf of a suspended application, within certain constraints.
+    optional: false
+    availability: creation
+    type: Modules.URLSession.SessionConfiguration

documentation/changelog.md

@@ -1,5 +1,8 @@
 # Change Log
 
+## 2.1.0
+Add support for upload tasks and more advanced session configuration.
+
 ## 2.0.0
 Refactored module to work on iOS 9 and prevent app submission failture. [MOD-2150]
 

documentation/index.md

@@ -59,16 +59,28 @@ To allow outstanding tasks to run until completion, call finishTasksAndInvalidat
 
 * Takes one argument, a session object : the session which the user wants to invalidate. 
 
-### backgroundDownloadTaskWithURL(session object, string)
+### addBackgroundDownloadTask(args)
 
 Creates a download task for the specified URL, within the provided session object and saves the results to a file.
 Once this function is called, the download starts automatically. The progress of the download can be monitored by listening 
 to `downloadprogress` , `downloadcompleted`, `sessioneventscompleted` and `sessioncompleted` events explained below.
 
-* Takes two arguments, 
-   * a session object : (Object created using createURLSession()) Session which with the new background task should be associated with.
+* Takes an object of arguments, 
+   * session[URLSession] : (Object created using createURLSession()) Session which with the new background task should be associated with.
    * url[string] : The string that provides the URL to be downloaded.
-   
+
+
+### addBackgroundUploadTask(args)
+
+Creates an upload task for the specified URL, within the provided session object and the file-blob to upload.
+Once this function is called, the upload starts automatically. The progress of the upload can be monitored by listening 
+to `uploadprogress` and `sessioncompleted` events explained below.
+
+* Takes an object of arguments, 
+   * session[URLSession] : (Object created using createURLSession()) Session which with the new background task should be associated with.
+   * url[string] : The string that provides the URL to upload to.
+   * data[TiBlob] : The file-blob to be uploaded.
+
 Returns the new created task's identifier number. 
 
 ## Events
@@ -113,7 +125,6 @@ usage :
 
 ### sessioncompleted
 
-
 Informs the app that the task finished transferring data.
 
 <strong>Important</strong>This event is exposed inside Ti.App.iOS Proxy.
@@ -122,8 +133,8 @@ usage :
 
 The following event information will be provided:	
 
-* taskIdentifier[int] : The task identifier number for the download task that finished.
-* success[boolean] : Indicates if the operation succeeded. Returns true if download succeeded, false otherwise. 
+* taskIdentifier[int] : The task identifier number for the download or upload task that finished.
+* success[boolean] : Indicates if the operation succeeded. Returns true if download or upload succeeded, false otherwise. 
 * errorCode[int] : The error code of the error, if any (potentially system-dependent).
 * message[string] : A string containing the localized description of the error. 
 
@@ -144,5 +155,5 @@ View the [change log](changelog.html) for this module.
 Please direct all questions, feedback, and concerns to [info@appcelerator.com](mailto:info@appcelerator.com?subject=iOS%20urlSesson%20Module). 
 
 ## License
-Copyright(c) 2010-2015 by Appcelerator, Inc. All Rights Reserved. Please see the LICENSE 
+Copyright(c) 2010-Present by Appcelerator, Inc. All Rights Reserved. Please see the LICENSE 
 file included in the distribution for further details.

ios/Classes/ComAppceleratorUrlSessionModule.h

@@ -1,22 +1,30 @@
 /**
- * ti.urlsession
- *
- * Created by Your Name
- * Copyright (c) 2015 Your Company. All rights reserved.
+ * Appcelerator Titanium Mobile
+ * Copyright (c) 2009-Present by Appcelerator, Inc. All Rights Reserved.
+ * Licensed under the terms of the Apache Public License
+ * Please see the LICENSE included with this distribution for details.
  */
 
 #import "TiModule.h"
-#import "SessionProxy.h"
-#import "SessionConfigurationProxy.h"
+#import "ComAppceleratorUrlSessionSessionProxy.h"
+#import "ComAppceleratorUrlSessionSessionConfigurationProxy.h"
 #import <UIKit/UIKit.h>
 #import <Foundation/Foundation.h>
 
 @interface ComAppceleratorUrlSessionModule : TiModule {}
 
--(SessionConfigurationProxy*)createURLSessionBackgroundConfiguration:(id)identifier;
--(SessionProxy*)createURLSession:(id)sessionConfiguration;
--(void)finishTasksAndInvalidate:(SessionProxy*)session;
--(void)invalidateAndCancel:(SessionProxy*)session;
--(NSNumber*)backgroundDownloadTaskWithURL:(id)args;
+- (id)createURLSessionBackgroundConfiguration:(id)args; // Deprecated in 2.1.0: Use "createSessionConfiguration" instead.
+
+- (id)createURLSession:(id)args; // Deprecated in 2.1.0: Use "createSession" instead.
+
+- (id)backgroundDownloadTaskWithURL:(id)args; // Deprecated in 2.1.0: Use "addBackgroundDownloadTask" instead.
+
+- (void)finishTasksAndInvalidate:(id)value; // Deprecated in 2.1.0: Use "Session.finishTasksAndInvalidate" instead.
+
+- (void)invalidateAndCancel:(id)value; // Deprecated in 2.1.0: Use "Session.invalidateAndCancel" instead.
+
+- (id)createSessionConfiguration:(id)args;
+
+- (id)createSession:(id)args;
 
 @end