======================================================================
Release notes for Ice Touch 1.0.0
======================================================================

Table of Contents
-----------------

  1. Introduction
  2. Ice Touch Feature Set
  3. SSL Support
  4. Loggers
  5. Garbage Collection
  6. Auto release pool
  7. AMI Invocations
  8. Xcode project settings


======================================================================
1. Introduction
======================================================================

Ice Touch offers an Objective-C language mapping, an Ice run time
for Mac OS X, and an Xcode SDK for Cocoa applications, the iPhone
and the iPod touch.

The Ice Touch distribution does not include any Ice services, but
its support for the complete Ice protocol means that your Ice Touch
applications can work seamlessly with existing Ice servers as well
as Ice services such as IceGrid, Glacier2, and IceStorm.


======================================================================
2. Ice Touch Feature Set
======================================================================

Ice Touch supports the following new features:

  - Objective-C mapping
  - Default servants

These topics are described in the manual.

Ice Touch currently lacks support for the following Ice features:

  - Asynchronous method dispatch (AMD)
  - Collocation optimization
  - Servant locators
  - Implicit contexts
  - Protocol plug-ins
  - Local interfaces
  - Ice.Application and Ice.Service helper classes
  - Ice.Stats interface

Ice Touch has limited support for:

  - SSL

    Refer to Section 3 below for more information.

  - UDP

    On the iPhone, UDP requests do not transparently establish a
    3G/Edge connection.


======================================================================
3. SSL Support
======================================================================

Ice Touch for Mac OS X and Cocoa uses the Ice for C++ SSL
protocol plug-in.

For the iPhone, Ice Touch SSL provides only a subset of this
functionality. Due to limitations in iPhone SSL support, the
following restriction applies:

  - Ice Touch servers cannot authenticate SSL clients.

Furthermore, the semantics of some IceSSL configuration properties
have changed, and new properties have been added. The IceSSL property
reference section of the Ice Touch manual provides complete details.

SSL support is not available for the iPhone Simulator.


======================================================================
4. Loggers
======================================================================

Custom loggers must be installed via ICEInitializationData. You cannot
use any of the Ice for C++ logger properties, such as Ice.UseSyslog,
and you cannot install a custom logger with a plug-in (Ice.Plugin.*).


======================================================================
5. Garbage Collection
======================================================================

For MacOS X and Cocoa, the Ice Touch run time is built with garbage
collection support.

For the iPhone and iPhone Simulator, since garbage collection is not
supported, you must use explicit retain/release.

Due to the lack of GC, the Ice Touch run time for iPhone and
iPhone Simulator cannot garbage collect graphs of objects containing
cycles. For example,

class Foo
{
    Foo next;
};

Foo a = [[Foo alloc] init];
Foo b = [[Foo alloc] init];
a.next = b;
b.next = a;

If you send this graph over the wire, your application will leak
memory unless you somehow retain the graph and manually break the
cycle.


======================================================================
6. Auto release pool
======================================================================

The Ice run time creates an NSAutoReleasePool object before each
server-side dispatched invocation and client-side AMI callback. The
pool is released once the dispatch is complete.


======================================================================
7. AMI Invocations
======================================================================

If you attempt to invoke an operation that returns values to the
client as a oneway operation, the Ice run time throws a
TwowayOnlyException. With Ice Touch, when this is done through an AMI
invocation, the exception is raised directly to the caller, instead of
being reported via the AMI exception callback. This is contrary to our other
language mappings, where the exception is reported via the AMI
callback.

======================================================================
8. Xcode project settings
======================================================================

For Cocoa and iPhone applications, which use the Xcode SDK, you must
add to "Additional SDKs"

  /Developer/SDKs/IceTouch-1.0/$(PLATFORM_NAME).sdk

In addition, for iPhone applications, when creating a new iPhone Xcode
project, you set the "Code Signing Resource Rules Path" to:

  $(SDKROOT)/ResourceRules.plist

To set the path, select "Target", press "Info", select the "Build" tab,
and press "Select".

If you do not do this, you will receive an error signing your
application when targeting iPhone 2.2 or later.

You must also add to the Frameworks folder:

 - CFNetwork.framework
 - Security.framework
 - Foundation.framework


For iPhone Simulator applications, the dynamically linked Ice libraries
must be copied into the application directory. For our iPhone demos,
this is done in the Xcode project with a post-build script as follows:

if [ $PLATFORM_NAME = iphonesimulator ]; then
  cp $ADDITIONAL_SDKS/usr/local/lib/*.dylib $BUILT_PRODUCTS_DIR/$CONTENTS_FOLDER_PATH
fi