# GPGData

> Inherits From:
>   GPGObject : NSObject

> Declared In:
>   GPGME/GPGData.h

## Class Description

A lot of data has to be exchanged between the user and the crypto engine, like plaintext messages, ciphertext, signatures and information about the keys. The technical details about exchanging the data information are completely abstracted by GPGME. The user provides and receives the data via GPGData instances, regardless of the communication protocol between GPGME and the crypto engine in use.

Data objects can be based on memory, files, or callback methods provided by the user (data source). Not all operations are supported by all objects.

Memory Based Data Buffers

Memory based data objects store all data in allocated memory. This is convenient, but only practical for an amount of data that is a fraction of the available physical memory. The data has to be copied from its source and to its destination, which can often be avoided by using one of the other data object. Here are the methods to initialize memory based data buffers:

-init |
-initWithData: |
-initWithDataNoCopy: |
-initWithContentsOfFile: |
-initWithContentsOfFile:atOffset:length: |

File Based Data Buffers

File based data objects operate directly on file descriptors or streams. Only a small amount of data is stored in core at any time, so the size of the data objects is not limited by GPGME. Here are the methods to initialize file based data buffers:

-initWithFileHandle: |

Callback Based Data Buffers

If neither memory nor file based data objects are a good fit for your application, you can provide a data source implementing NSObject(GPGDataSource) methods and create a data object with this data source. Here are the methods to initialize callback based data buffers:

-initWithDataSource: |

## Defined Types

> #### Synopsis:

> `typedef enum {
> GPGDataEncodingNone = 0,
> GPGDataEncodingBinary = 1,
> GPGDataEncodingBase64 = 2,
> GPGDataEncodingArmor = 3
> } GPGDataEncoding;`

> #### Description:

> The GPGDataEncoding type specifies the encoding of a GPGData object. This encoding is useful to give the backend a hint on the type of data. The following data types are available:

> GPGDataEncodingNone | This specifies that the encoding is not known. This is the default for a new data object. The backend will try its best to detect the encoding automatically.
> GPGDataEncodingBinary | This specifies that the data is encoding in binary form; i.e. there is no special encoding.
> GPGDataEncodingBase64 | This specifies that the data is encoded using the Base-64 encoding scheme as used by MIME and other protocols.
> GPGDataEncodingArmor | This specifies that the data is encoded in an armored form as used by OpenPGP and PEM.

> #### Synopsis:

> `typedef enum {
> GPGDataStartPosition = 0,
> GPGDataCurrentPosition = 1,
> GPGDataEndPosition = 2
> } GPGDataOffsetType;`

> #### Description:

> The GPGDataOffsetType type specifies how the offset should be interpreted when repositioning read/write (-seekToFileOffset:offsetType: and -data:seekToFileOffset:offsetType:). It must be one of the following symbolic constants:

> GPGDataStartPosition | Offset is a count of characters from the beginning of the data object.
> GPGDataCurrentPosition | Offset is a count of characters from the current file position. This count may be positive or negative.
> GPGDataEndPosition | Offset is a count of characters from the end of the data object. A negative count specifies a position within the current extent of the data object; a positive count specifies a position past the current end. If you set the position past the current end, and actually write data, you will extend the data object with zeros up to that position.

## Symbolic Constants

> #### Synopsis:

> `GPGDATA_H`

## Instance Variables

> `id _objectReference;`
> `void *_callbacks;`

> _objectReference | No description.
> _callbacks | No description.

## Method Types

> Creating memory based data buffers
>   - init
>   - initWithData:
>   - initWithDataNoCopy:
>   - initWithContentsOfFile:
>   - initWithContentsOfFile:atOffset:length:
> Creating file based data buffers
>   - initWithFileHandle:
> Creating callback based data buffers
>   - initWithDataSource:
> Encoding
>   - encoding
>   - setEncoding:
> Manipulating data buffers
>   - seekToFileOffset:offsetType:
>   - readDataOfLength:
>   - writeData:
> Convenience initializer
>   - initWithString:
> Convenience methods
>   - length
>   - data
>   - string
>   - availableData
>   - availableDataLength
>   - isAtEnd
>   - rewind

## Instance Methods

### availableData

`- (NSData *)availableData`

Returns a copy of data, read from current position, up to end of data.

Can raise a GPGException of type GPGError_E*.

### availableDataLength

`- (unsigned long long)availableDataLength`

Returns the amount of bytes available without changing the read pointer. This is not supported by all types of data objects.

If this method is not supported, a GPGException is raised, with error GPGErrorInvalidType.

If end of data object is reached or no data is currently available, it returns 0. To know if there are more bytes to read, you must invoke -isAtEnd.

Can raise a GPGException of type GPGError_E*.

### data

`- (NSData *)data`

Convenience method. Returns a copy of all data. It rewinds receiver, then reads data until EOF, and returns it.

If this method is not supported, a GPGException is raised, with error GPGErrorInvalidType.

Can raise a GPGException.

### encoding

`- (GPGDataEncoding)encoding`

Returns the encoding of the data object.

### init

`- (id)init`

Data is created without content and is memory based.

Can raise a GPGException; in this case, a release is sent to self.

### initWithContentsOfFile:

`- (id)initWithContentsOfFile:(NSString *)filename`

Immediately opens file named filename (which must be an absolute path) and copies content into memory; then it closes file.

Can raise a GPGException; in this case, a release is sent to self.

### initWithContentsOfFile:atOffset:length:

`- (id)initWithContentsOfFile:(NSString *)filename atOffset:(unsigned long long)offset length:(unsigned long long)length`

Immediately opens file and copies partial content into memory; then it closes file.

Can raise a GPGException; in this case, a release is sent to self.

### initWithData:

`- (id)initWithData:(NSData *)someData`

Copies someData's bytes.

Can raise a GPGException; in this case, a release is sent to self.

### initWithDataNoCopy:

`- (id)initWithDataNoCopy:(NSData *)someData`

Doesn't copy someData, but retains it.

Can raise a GPGException; in this case, a release is sent to self.

### initWithDataSource:

`- (id)initWithDataSource:(id)dataSource`

dataSource must implement some of the methods declared in NSObject(GPGDataSource) informal protocol. dataSource is not retained. dataSource is invoked to read/write data on-demand, and it can supply the data in any way it wants; this is the most flexible data type GPGME provides.

Can raise a GPGException; in this case, a release is sent to self.

### initWithFileHandle:

`- (id)initWithFileHandle:(NSFileHandle *)fileHandle`

Uses fileHandle to read from (if used as an input data object) and write to (if used as an output data object). fileHandle is retained.

When using the data object as an input buffer, the method might read a bit more from the file handle than is actually needed by the crypto engine in the desired operation because of internal buffering.

Can raise a GPGException; in this case, a release is sent to self.

### initWithString:

`- (id)initWithString:(NSString *)string`

Convenience method. Gets data from string using UTF8 encoding, and invokes -initWithData:.

Can raise a GPGException; in this case, a release is sent to self.

### isAtEnd

`- (BOOL)isAtEnd`

Returns YES if there are no more bytes to read (EOF). Read pointer is not moved.

If this method is not supported, a GPGException is raised, with error GPGErrorInvalidType.

Can raise a GPGException of type GPGError_E*.

### length

`- (unsigned long long)length`

Convenience method. Returns length of all data. It rewinds receiver, then reads available data length and returns it. Read pointer is reset.

If this method is not supported, a GPGException is raised, with error GPGErrorInvalidType.

Can raise a GPGException.

### readDataOfLength:

`- (NSData *)readDataOfLength:(unsigned long long)length`

Reads up to length bytes and returns them wrapped in a NSData. Reading starts from the current position. Returned data has the appropriate size, smaller or equal to length. Returns nil when there isn't anything more to read (EOF).

Can raise a GPGException of type GPGError_E*.

### rewind

`- (void)rewind`

Prepares data in a way that the next call to -readDataOfLength: or -writeData: starts at the beginning of the data.

Can raise a GPGException of type GPGError_E*.

### seekToFileOffset:offsetType:

`- (unsigned long long)seekToFileOffset:(unsigned long long)offset offsetType:(GPGDataOffsetType)offsetType`

Sets the current position from where the next read or write starts in the data object to offset, relativ to offsetType. Returns the resulting file position, measured in bytes from the beginning of the data object. You can use this feature together with GPGDataCurrentPosition to read the current read/write position.

Can raise a GPGException of type GPGError_E*.

### setEncoding:

`- (void)setEncoding:(GPGDataEncoding)encoding`

Sets the encoding of the data object.

Can raise a GPGException.

### string

`- (NSString *)string`

Convenience method. Returns a copy of all data as string, using UTF8 string encoding (or ISOLatin1 if it cannot be decoded as UTF8). It rewinds receiver, then reads data until EOF, and returns a string initialized with it.

Invoking this method has sense only when you know that data corresponds to a string!

Can raise a GPGException.

### writeData:

`- (unsigned long long)writeData:(NSData *)data`

Writes data bytes by copying them. Writing starts from the current position. Returns the number of bytes written.

Can raise a GPGException of type GPGError_E*.

Version 1.1 Copyright ©2005 by Mac GPG Project. All Rights Reserved. Sun Jan 23 16:54:41 2005