Class: GPGME::Data

Inherits:
Object
  • Object
show all
Defined in:
lib/gpgme/data.rb,
ext/gpgme/gpgme_n.c

Overview

A class whose purpose is to unify the way we work with the data (both input and output). Most of the calls expect instances of this class, or will try to create one from your parameters.

Read the #read, #write and #seek methods for the most commonly used methods.

Constant Summary

BLOCK_SIZE = 
4096

Class Method Summary (collapse)

Instance Method Summary (collapse)

Class Method Details

+ (Object) empty!

Create a new instance with an empty buffer.



60
61
62
63
64
65
66
 
# File 'lib/gpgme/data.rb', line 60

def empty!
  rdh = []
  err = GPGME::gpgme_data_new(rdh)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  rdh.first
end

+ (Object) from_callbacks(callbacks, hook_value = nil)

Create a new instance from the specified callbacks.



92
93
94
95
96
97
98
 
# File 'lib/gpgme/data.rb', line 92

def from_callbacks(callbacks, hook_value = nil)
  rdh = []
  err = GPGME::gpgme_data_new_from_cbs(rdh, callbacks, hook_value)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  rdh.first
end

+ (Object) from_fd(fd)

Create a new instance from the specified file descriptor.



83
84
85
86
87
88
89
 
# File 'lib/gpgme/data.rb', line 83

def from_fd(fd)
  rdh = []
  err = GPGME::gpgme_data_new_from_fd(rdh, fd)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  rdh.first
end

+ (Object) from_io(io)

Create a new instance associated with a given IO.



78
79
80
 
# File 'lib/gpgme/data.rb', line 78

def from_io(io)
  from_callbacks(IOCallbacks.new(io))
end

+ (Object) from_str(string)

Create a new instance with internal buffer.



69
70
71
72
73
74
75
 
# File 'lib/gpgme/data.rb', line 69

def from_str(string)
  rdh = []
  err = GPGME::gpgme_data_new_from_mem(rdh, string, string.length)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  rdh.first
end

+ (Object) new(object = nil)

We implement self.new instead of initialize because objects are actually instantiated through the C API with stuff like gpgme_data_new.

We try to create a GPGME::Data smartly depending on the object passed, and if another GPGME::Data object is passed, it just returns it, so when in doubt, you can always pass a GPGME::Data object.

Examples:

empty

data = GPGME::Data.new
data.write("stuff")

from a string

data = GPGME::Data.new("From a string")

from a file

data = GPGME::Data.new(File.open("secure.pass"))

from a file descriptor

data = GPGME::Data.new(0) # Standard input
data = GPGME::Data.new(1) # Standard output

file = File.open("secure.pass")
data = GPGME::Data.new(file.fileno) # file descriptor


41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/gpgme/data.rb', line 41

def new(object = nil)
  if object.nil?
    empty!
  elsif object.is_a?(Data)
    object
  elsif object.is_a?(Integer)
    from_fd(object)
  elsif object.respond_to? :to_str
    from_str(object.to_str)
  elsif object.respond_to? :to_io
    from_io(object.to_io)
  elsif object.respond_to? :open
    from_io(object.open)
  elsif defined?(StringIO) and object.is_a?(StringIO)
    from_io(object)
  end
end

Instance Method Details

- (Object) encoding

Return the encoding of the underlying data.



163
164
165
 
# File 'lib/gpgme/data.rb', line 163

def encoding
  GPGME::gpgme_data_get_encoding(self)
end

- (Object) encoding=(encoding)

Sets the encoding for this buffer. Accepts only values in one of the DATA_ENCODING_* constants.

Raises:



172
173
174
175
176
177
 
# File 'lib/gpgme/data.rb', line 172

def encoding=(encoding)
  err = GPGME::gpgme_data_set_encoding(self, encoding)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  encoding
end

- (Object) read(length = nil)

Read at most length bytes from the data object, or to the end of file if length is omitted or is nil.

Examples:

data = GPGME::Data.new("From a string")
data.read # => "From a string"
data = GPGME::Data.new("From a string")
data.read(4) # => "From"


112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/gpgme/data.rb', line 112

def read(length = nil)
  if length
    GPGME::gpgme_data_read(self, length)
  else
    buf = String.new
    loop do
      s = GPGME::gpgme_data_read(self, BLOCK_SIZE)
      break unless s
      buf << s
    end
    buf
  end
end

- (Object) seek(offset, whence = IO::SEEK_SET)

Seek to a given offset in the data object according to the value of whence.

Examples:

going to the beginning of the buffer after writing something

data = GPGME::Data.new("Some data")
data.read # => "Some data"
data.read # => ""
data.seek 0
data.read # => "Some data"


137
138
139
 
# File 'lib/gpgme/data.rb', line 137

def seek(offset, whence = IO::SEEK_SET)
  GPGME::gpgme_data_seek(self, offset, IO::SEEK_SET)
end

- (Object) to_s

Return the entire content of the data object as string.



181
182
183
184
185
186
187
188
189
 
# File 'lib/gpgme/data.rb', line 181

def to_s
  pos = seek(0, IO::SEEK_CUR)
  begin
    seek(0)
    read
  ensure
    seek(pos)
  end
end

- (Object) write(buffer, length = buffer.length)

Writes length bytes from buffer into the data object. Writes the full buffer if no length passed.

Examples:

data = GPGME::Data.new
data.write "hola"
data.seek 0
data.read # => "hola"
data = GPGME::Data.new
data.write "hola", 2
data.seek 0
data.read # => "ho"


157
158
159
 
# File 'lib/gpgme/data.rb', line 157

def write(buffer, length = buffer.length)
  GPGME::gpgme_data_write(self, buffer, length)
end