<!--
#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
#  KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#
-->

# API Changes in cordova-ios-4.0

* CDVViewController.h (_updated_)
* CDVPlugin.h (_updated_)
* CDVPluginResult.h (_updated_)
* NSData+Base64.h (_removed_)
* CDVAppDelegate.h (_new_) 
* CDVJSON.h (_removed_)
* CDVJSON\_private.h (_removed_)
* CDVWebViewEngineProtocol.h (_new_)
* CDVURLRequestFilter.h (_new_)
* NSDictionary+CordovaPreferences.h (_new_)
* CDVWebViewDelegate.h (_removed_)
* NSDictionary+Extensions.h (_removed_)
* NSArray+Comparisons.h (_removed_)
* CDVHandleOpenURL.h (_removed_)
* CDVLocalStorage.h (_removed_)
* UIDevice+Extensions.h (_removed_)
* CDVShared.h (_removed_)
* CDVDebug.h (_removed_)
* Conditional Compilation

- - -

## CDVViewController.h (_updated_)


### Removed:

Methods:

    + (NSDictionary*)getBundlePlist:(NSString*)
    + (NSString*)applicationDocumentsDirectory
    - (void)javascriptAlert:(NSString*)
    - (void)printMultitaskingInfo
    - createGapView
    - (BOOL)URLisAllowed:(NSURL*)url

Properties:

    @property BOOL loadFromString

### Added:

Properties:

    @property id<CDVWebViewEngineProtocol> webViewEngine
    @property NSInteger* userAgentLockToken

### Modified:

Methods:

    - (UIView*)newCordovaViewWithFrame:(CGRect)bounds

Properties:

    @property UIView* webView

### Upgrade Notes:

The `webView` property is a `UIView` now, to take into account the different type of WebView engines that might be installed. 

To test and cast the `webView` property to `UIWebView`:

    if ([self.webView isKindOfClass:[UIWebView class]) {
        // call a UIWebView specific method here, for example
        [((UIWebView*)self.webView) goBack];
    }

- - -

## CDVPlugin.h (_updated_)

### Removed:

Methods:

    - (CDVPlugin*)initWithWebView:(UIWebView*)
    - (NSString*)writeJavascript:(NSString*)
    - (NSString*)success:(CDVPluginResult*) callbackId:(NSString*)
    - (NSString*)error:(CDVPluginResult*) callbackId:(NSString*)

Properties:

    @property CDVWhitelist* whitelist

### Added:

Methods:

    - (NSURL*)errorURL;
    - (BOOL)shouldOverrideLoadWithRequest:(NSURLRequest*) navigationType:(UIWebViewNavigationType)

Properties:

    @property id<CDVWebViewEngineProtocol> webViewEngine


### Modified:

    @property UIView* webView


### Optional:

Methods:

    - (BOOL)shouldOverrideLoadWithRequest:(NSURLRequest*) navigationType:(UIWebViewNavigationType)

### Upgrade Notes:

Put your initialization code from `initWithWebView` into `pluginInitialize`. `pluginInitialize` is backwards-compatible, it has been there since cordova-ios-2.x. 

For example, if you have this:

    - (CDVPlugin*) initWithWebView:(UIWebView*)webView {
        self = [super initWithWebView:webView];
        if (self) {
            // Initialization code here
        }
        return self;
    }
 
 Move your initialization code to:
 
    - (void) pluginInitialize {
        // Initialization code here
    }

- - -

## CDVPluginResult.h (_updated_)

### Added:

Methods:

    + (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAsNSInteger:(NSInteger)theMessage;
    + (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAsNSUInteger:(NSUInteger)theMessage;


- - -

## NSData+Base64.h (_removed_)

This class has been removed.

### Removed:

Methods:

    + (NSData*)dataFromBase64String:(NSString*)aString CDV_DEPRECATED(3.8 .0, "Use cdv_dataFromBase64String");
    - (NSString*)base64EncodedString CDV_DEPRECATED(3.8 .0, "Use [NSData cdv_base64EncodedString]");
    + (NSData*)cdv_dataFromBase64String:(NSString*)aString;
    - (NSString*)cdv_base64EncodedString;
    
### Upgrade Notes:

Plugin authors are encouraged to use the (iOS 7+) base64 encoding and decoding methods available in [NSData](https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSData_Class/) instead.

    // Decode a Base64 encoded string
    NSData* data = [[NSData alloc] initWithBase64EncodedString:encodedString options:0]
    
    // Encode a string to Base64
    NSString* encodedString = [data base64EncodedStringWithOptions:0];

- - -

## CDVAppDelegate.h (_new_)

This class is new. The default template's `AppDelegate` class inherits from this now for you to override.
    
### Upgrade Notes:

Apps that add code in the default template's old `AppDelegate.m` should add the appropriate function override in the new `AppDelegate.m`. Don't forget to call the superclass' implementation as well in your override.

- - -

## CDVJSON.h (_removed_)

These Objective-C Categories have been **removed**. 

### Upgrade Notes:

To convert from an NSArray/NSDictionary object to a JSON string:

    id object; // this is the NSArray/NSDictionary to convert from
    NSError* error = nil;
    NSString* jsonString = nil;
    NSData* jsonData = [NSJSONSerialization dataWithJSONObject:object
                                                       options:NSJSONWritingPrettyPrinted
                                                         error:&error];
                                                         
    if (error == nil) {
        jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
    }

To convert from an NSString to an NSArray/NSDictionary object:

    NSString* jsonString; // this is the JSON to convert from
    NSError* error = nil;
    id object = [NSJSONSerialization JSONObjectWithData:[jsonString dataUsingEncoding:NSUTF8StringEncoding]
                                                options:NSJSONReadingMutableContainers
                                                  error:&error];

    if (error != nil) {
        NSLog(@"NSString can't be converted to an NSArray/NSDictionary error: %@", [error localizedDescription]);
    }

- - -

## CDVJSON\_private.h (_removed_)

These Objective-C Categories have been **removed** from the public API, and is private to CordovaLib.

- - -

## CDVWebViewEngineProtocol.h (_new_)

This is new in cordova-ios-4.0. An Objective-C protocol for plugins to implement, if they want to be an alternative WebView engine.

- - -

## NSDictionary+CordovaPreferences.h (_new_)

This is new in cordova-ios-4.0. An Objective-C Category helper for NSDictionary to get/set preferences.

- - -

## CDVWebViewDelegate.h (_removed_)

This protocol has been **removed** from the public API, and is part of a private plugin to CordovaLib (CDVUIWebViewEngine).

- - -

## NSDictionary+Extensions.h (_removed_)

This Objective-C Category has been **removed**.

- - -

## NSArray+Comparisons.h (_removed_)

This Objective-C category has been **removed**. 

### Upgrade Notes:

The Objective-C Category method was used as a helper for the `arguments` property of a `CDVInvokedURLCommand` object. Use the `argumentAtIndex` [methods provided](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVInvokedUrlCommand.h) in the `CDVInvokedURLCommand` object instead. 

- - -

## CDVHandleOpenURL.h (_removed_)

This plugin has been **removed** from the public API, and is now private to CordovaLib.

- - -

## CDVLocalStorage.h (_removed_)

This plugin has been **removed** from the public API, and is now private to CordovaLib.

- - -

## UIDevice+Extensions.h (_removed_)

This implementation has been **removed** and is part of the core plugin `cordova-plugin-device`.

- - -

## CDVShared.h (_removed_)

This legacy header has been **removed**; it was for core plugin compatibility that has been not been needed [since the Aug 2014 core plugin release](https://cordova.apache.org/news/2014/08/11/plugins-release.html).

- - -

## CDVDebug.h (_removed_)

This file has been **removed** from the public API, and is private to CordovaLib.

- - -

## Conditional Compilation

You can conditionally compile code based on the cordova-ios platform version that is installed. This might be for API calls that have no backwards-compatible equivalents. 

    // this import below must be declared first
    #import <Cordova/CDVAvailability.h>
    
    #ifdef __CORDOVA_4_0_0
        // Execute/declare code on cordova-ios-4.x or newer 
    #else
        // Execute/declare code for cordova-ios versions *less than* 4.x 
    #endif
 
 OR

    #ifndef __CORDOVA_4_0_0
        // Execute/declare code for cordova-ios versions *less than* 4.x 
    #endif
