GPGData

Inherits From:

GPGObject : NSObject

Declared In:

GPGME/GPGData.h

Class Description

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*.