Merge pull request #510 from gnustep/file-handle-refactor

feat(NSFileHandle): Add new APIs with error handling, and refactor GSFileHandle

Author: rfm

Headers/Foundation/NSFileHandle.h

@@ -73,9 +73,29 @@ GS_EXPORT_CLASS
 
 - (NSData*) availableData;
 - (NSData*) readDataToEndOfFile;
-- (NSData*) readDataOfLength: (unsigned int)len;
+- (NSData*) readDataOfLength: (NSUInteger)len;
 - (void) writeData: (NSData*)item;
 
+#if OS_API_VERSION(MAC_OS_X_VERSION_10_15, GS_API_LATEST)
+/**
+ * Writes the specified data synchronously to the file handle.
+ */
+- (BOOL) writeData: (NSData *) data 
+             error: (NSError **) error;
+
+/**
+ * Reads the data synchronously up to the specified number of bytes.
+ */
+- (NSData *) readDataUpToLength: (NSUInteger) length 
+                          error: (NSError **) error;
+
+/**
+ * Reads the data synchronously up to the end of file or maximum number of
+ * bytes.
+ */
+- (NSData *) readDataToEndOfFileAndReturnError: (NSError **) error;
+#endif
+
 // Asynchronous I/O operations
 
 - (void) acceptConnectionInBackgroundAndNotify;
@@ -93,23 +113,36 @@ GS_EXPORT_CLASS
 - (unsigned long long) seekToEndOfFile;
 - (void) seekToFileOffset: (unsigned long long)pos;
 
-// Operations on file
+#if OS_API_VERSION(MAC_OS_X_VERSION_10_15, GS_API_LATEST)
+/**
+ * Get the current position of the file pointer within the file.
+ */
+- (BOOL) getOffset: (unsigned long long *) offsetInFile 
+             error: (NSError **) error;
 
-- (void) closeFile;
-- (void) synchronizeFile;
-- (void) truncateFileAtOffset: (unsigned long long)pos;
+/**
+ * Sets the file pointer at the end of the file and returns the new file offset.
+ */
+- (BOOL) seekToEndReturningOffset: (unsigned long long *) offsetInFile 
+                            error: (NSError **) error;
+
+/**
+ * Sets the file pointer to the specified offset within the file.
+ */
+- (BOOL) seekToOffset: (unsigned long long) offset 
+                error: (NSError **) error;
 
-#if OS_API_VERSION(MAC_OS_X_VERSION_10_15, GS_API_LATEST)
-- (BOOL) getOffset: (out unsigned long long *)offsetInFile 
-             error: (out NSError **)error;
-- (BOOL) seekToEndReturningOffset: (out unsigned long long *)offsetInFile 
-                            error: (out NSError **)error;
-- (BOOL) seekToOffset: (unsigned long long)offset 
-                error: (out NSError **)error;
 - (BOOL) truncateAtOffset: (unsigned long long)offset 
                     error: (out NSError **)error;
+
 #endif
 
+// Operations on file
+
+- (void) closeFile;
+- (void) synchronizeFile;
+- (void) truncateFileAtOffset: (unsigned long long)pos;
+
 @end
 
 // Notification names.