# DSFileFetcher

The `DSFileFetcher` class is a utility class that partitions a multi-page image file into multiple independent `ImageData` objects. It inherits from the `DSImageSourceAdapter` class.

## Definition

*Assembly:* DynamsoftCaptureVisionBundle.xcframework

<div class="sample-code-prefix"></div>
>- Objective-C
>- Swift
>
>1. 
```objc
@interface DSFileFetcher : DSImageSourceAdapter
```
2. 
```swift
class FileFetcher : ImageSourceAdapter
```

## Methods

| Method | Description |
| ------ | ----------- |
| [`setFileWithPath`](#setfilewithpath) | Sets the file with a file path. |
| [`setFileWithBytes`](#setfilewithbytes) | Sets the file with file bytes. |
| [`setFileWithBuffer`](#setfilewithbuffer) | Sets the file with a `DSImageData` object. |
| [`setFileWithImage`](#setfilewithimage) | Sets the file with a `UIImage`. |
| [`hasNextImageToFetch`](#hasnextimagetofetch) | Whether there is a next image to fetch. |
| [`getImage`](#getimage) | Get the image data of the image. |
| [`setPages`](#setpages) | Set the pages to read. |

The following methods & attributes are inherited from [`DSImageSourceAdapter`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md).

| Attributes | Type | Description |
| ---------- | ---- | ----------- |
| [`bufferEmpty`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#bufferempty) | *BOOL* | The read only property determines whether the buffer is currently empty. |
| [`bufferOverflowProtectionMode`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#bufferoverflowprotectionmode) | *DSBufferOverflowProtectionMode* | Sets the behavior for handling new incoming images when the buffer is full. |
| [`colourChannelUsageType`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#colourchannelusagetype) | *colourChannelUsageType* | Sets the usage type for color channels in images. |
| [`hasNextImageToFetch`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#hasnextimagetofetch) | *BOOL* | Determines whether there are more images available to fetch. |
| [`imageCount`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#imagecount) | *NSUInteger* | The property defines the current number of images in the buffer. |
| [`maxImageCount`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#maximagecount) | *NSUInteger* | The property defines the maximum number of images that can be buffered. |

| Method | Description |
| ------ | ----------- |
| [`addImageToBuffer`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#addimagetobuffer) | Adds an image to the internal buffer. |
| [`clearBuffer`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#clearbuffer) | Clears all images from the buffer, resetting the state for new image fetching. |
| [`getImage`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#getimage) | Get a buffered image. Implementing classes should return a Promise that resolves with an instance of `DSImageData`. |
| [`hasImage`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#hasimage) | Checks if an image with the specified ID is present in the buffer. |
| [`setErrorListener`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#seterrorlistener) | Sets an error listener to receive notifications about errors that occur during image source operations. |
| [`setNextImageToReturn`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#setnextimagetoreturn) | Sets the processing priority of a specific image. This can affect the order in which images are returned by `getImage`. |
| [`startFetching`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#startfetching) | Start fetching images from the source to the Video Buffer of ImageSourceAdapter. |
| [`stopFetching`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/core/basic-structures/image-source-adapter.md#stopfetching) | Stop fetching images from the source to the Video Buffer of ImageSourceAdapter. |

### setFileWithPath

Sets the file with a file path.

<div class="sample-code-prefix"></div>
>- Objective-C
>- Swift
>
>1. 
```objc
-(BOOL)setFileWithPath:(NSString *)filePath
                 error:(NSError *_Nullable *_Nullable)error;
```
2. 
```swift
func setFileWithPath( _filePath: String) throws
```

**Parameters**

`filePath`: The file path.

`error`: An `NSError` pointer. If an error occurs, it will represent the error information.

**Error**

| Error Code | Value | Description |
| :--------- | :---- | :---------- |
| EC_FILE_NOT_FOUND | -10005 | The file is not found. |
| EC_FILE_TYPE_NOT_SUPPORTED | -10006 | The file type is not supported. |

### setFileWithBytes

Sets the file with file bytes.

<div class="sample-code-prefix"></div>
>- Objective-C
>- Swift
>
>1. 
```objc
-(BOOL)setFileWithBytes:(NSData *)fileBytes
                  error:(NSError *_Nullable *_Nullable)error;
```
2. 
```swift
func setFileWithBytes( _fileBytes: Data) throws
```

**Parameters**

`fileBytes`: The file bytes.

`error`: An `NSError` pointer. If an error occurs, it will represent the error information.

**Error**

| Error Code | Value | Description |
| :--------- | :---- | :---------- |
| EC_NULL_POINTER | -10002 | The fileBytes you input is null. |

### setFileWithBuffer

Sets the file with a `DSImageData` object.

<div class="sample-code-prefix"></div>
>- Objective-C
>- Swift
>
>1. 
```objc
-(BOOL)setFileWithBuffer:(DSImageData *)buffer
                   error:(NSError *_Nullable *_Nullable)error;
```
2. 
```swift
func setFileWithBuffer( _buffer: ImageData) throws
```
**Parameters**

`buffer`: The image data.

`error`: An `NSError` pointer. If an error occurs, it will represent the error information.

**Error**

| Error Code | Value | Description |
| :--------- | :---- | :---------- |
| EC_NULL_POINTER | -10002 | The fileBytes you input is null. |

### setFileWithImage

Sets the file with a `UIImage`.

<div class="sample-code-prefix"></div>
>- Objective-C
>- Swift
>
>1. 
```objc
-(BOOL)setFileWithImage:(UIImage *)image
                  error:(NSError *_Nullable *_Nullable)error;
```
2. 
```swift
func setFileWithImage( _image: UIImage) throws
```
**Parameters**

`image`: A `UIImage`.

`error`: An `NSError` pointer. If an error occurs, it will represent the error information.

**Error**

| Error Code | Value | Description |
| :--------- | :---- | :---------- |
| EC_NULL_POINTER | -10002 | The fileBytes you input is null. |

### hasNextImageToFetch

Whether there is a next image to fetch.

<div class="sample-code-prefix"></div>
>- Objective-C
>- Swift
>
>1. 
```objc
-(BOOL)hasNextImageToFetch;
```
2. 
```swift
func hasNextImageToFetch() -> Bool
```

**Return Value**

A bool value that indicates whether there is a next image to fetch.

### setPages

Set the pages to read.

<div class="sample-code-prefix"></div>
>- Objective-C
>- Swift
>
>1. 
```objc
-(BOOL)setPages:(NSArray<NSNumber *> *)pages
          error:(NSError *_Nullable *_Nullable)error;
```
2. 
```swift
func setPages(_ pages: NSArray) throws -> BOOL
```

**Parameters**

`pages`: An array that contains all the pages to read.  
`error`: An `NSError` pointer. If an error occurs, it will represent the error information.

**Error**

| Error Code | Value | Description |
| :--------- | :---- | :---------- |
| EC_FILE_NOT_FOUND  | -10005 | File not found. |
| EC_FILE_TYPE_NOT_SUPPORTED  | -10006 | The file type is not supported. |
| EC_IMAGE_READ_FAILED  | -10012 | Failed to read the image. |