NSData: Improve error handling and new initialiser

Instead of printing out a warning, the underlying file reading function
creates proper NSError objects, that are returned to the user.

The following initializers were implemented:
-[NSData initWithContentsOfFile:options:error:]
-[NSData initWithContentsOfURL:options:error:]
+[NSData dataWithContentsOfFile:options:error:]
+[NSData dataWithContentsOfURL:options:error:]

Additionally NSDataReadingOptions was added to NSData.h.
Please note that NSDataReadingMappedIfSafe, and NSDataReadingMappedAlways
currently have no effect, and need to be implemented properly.

Author: hmelder

Headers/Foundation/NSData.h

@@ -39,6 +39,15 @@ extern "C" {
 @class	NSURL;
 #endif
 
+enum {
+    NSDataReadingMappedIfSafe =   1UL << 0,    // Suggests using memory mapping for the file if it can be done securely
+    NSDataReadingUncached =       1UL << 1,    // Suggests avoiding file system caching for the read operation
+#if OS_API_VERSION(MAC_OS_X_VERSION_10_7,GS_API_LATEST)
+    NSDataReadingMappedAlways =   1UL << 3,    // Strongly requests memory mapping the file; overrides MappedIfSafe if both are set
+#endif
+};
+typedef NSUInteger NSDataReadingOptions;
+
 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6,GS_API_LATEST)
 enum {
   NSDataSearchBackwards = (1UL << 0),
@@ -95,9 +104,15 @@ GS_EXPORT_CLASS
                               length: (NSUInteger)bufferSize
                         freeWhenDone: (BOOL)shouldFree;
 #endif
++ (instancetype)dataWithContentsOfFile: (NSString *)path
+                               options: (NSDataReadingOptions)readOptionsMask
+                                 error: (NSError **)errorPtr;
 + (instancetype) dataWithContentsOfFile: (NSString*)path;
 + (instancetype) dataWithContentsOfMappedFile: (NSString*)path;
 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
++ (instancetype) dataWithContentsOfURL: (NSURL *)url
+                               options: (NSDataReadingOptions)readOptionsMask
+                                 error: (NSError **)errorPtr;
 + (instancetype) dataWithContentsOfURL: (NSURL*)url;
 #endif
 + (instancetype) dataWithData: (NSData*)data;
@@ -127,9 +142,15 @@ GS_EXPORT_CLASS
                         freeWhenDone: (BOOL)shouldFree;
 #endif
 - (instancetype) initWithContentsOfFile: (NSString*)path;
+- (instancetype) initWithContentsOfFile:(NSString *) path 
+                                options:(NSDataReadingOptions) readOptionsMask 
+                                  error:(NSError **) errorPtr;
 - (instancetype) initWithContentsOfMappedFile: (NSString*)path;
 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
 - (instancetype) initWithContentsOfURL: (NSURL*)url;
+- (instancetype) initWithContentsOfURL: (NSURL *)url
+                               options: (NSDataReadingOptions)readOptionsMask
+                                 error: (NSError **)errorPtr;
 #endif
 - (instancetype) initWithData: (NSData*)data;