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 collapse

BLOCK_SIZE = 
4096

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.empty! ⇒ Object

Create a new instance with an empty buffer.



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

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

.from_callbacks(callbacks, hook_value = nil) ⇒ Object

Create a new instance from the specified callbacks.



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

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

.from_fd(fd) ⇒ Object

Create a new instance from the specified file descriptor.



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

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

.from_io(io) ⇒ Object

Create a new instance associated with a given IO.



76
77
78
 
# File 'lib/gpgme/data.rb', line 76

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

.from_str(string) ⇒ Object

Create a new instance with internal buffer.



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

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

.new(object = nil) ⇒ Object

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
 
# 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)
  end
end

Instance Method Details

#encoding ⇒ Object

Return the encoding of the underlying data.



161
162
163
 
# File 'lib/gpgme/data.rb', line 161

def encoding
  GPGME::gpgme_data_get_encoding(self)
end

#encoding=(encoding) ⇒ Object

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

Raises:



170
171
172
173
174
175
 
# File 'lib/gpgme/data.rb', line 170

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

#read(length = nil) ⇒ Object

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"


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

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

#seek(offset, whence = IO::SEEK_SET) ⇒ Object

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"


135
136
137
 
# File 'lib/gpgme/data.rb', line 135

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

#write(buffer, length = buffer.length) ⇒ Object

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"


155
156
157
 
# File 'lib/gpgme/data.rb', line 155

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