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.



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

.from_callbacks(callbacks, hook_value = nil) ⇒ Object

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

.from_fd(fd) ⇒ Object

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

.from_io(io) ⇒ Object

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

.from_str(string) ⇒ Object

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.bytesize)
  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
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

#encoding ⇒ Object

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

#encoding=(encoding) ⇒ Object

Sets the encoding for this buffer. Accepts only integer values 0 to 7:

0 = GPGME_DATA_ENCODING_NONE (Not specified) 1 = GPGME_DATA_ENCODING_BINARY 2 = GPGME_DATA_ENCODING_BASE64 3 = GPGME_DATA_ENCODING_ARMOR (Either PEM or OpenPGP Armor) 4 = GPGME_DATA_ENCODING_URL (LF delimited URL list) 5 = GPGME_DATA_ENCODING_URLESC (Ditto, but percent escaped) 6 = GPGME_DATA_ENCODING_URL0 (Nul delimited URL list) 7 = GPGME_DATA_ENCODING_MIME (Data is a MIME part)

Raises:



180
181
182
183
184
185
 
# File 'lib/gpgme/data.rb', line 180

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

#file_name ⇒ Object

Return the file name of the underlying data.



189
190
191
 
# File 'lib/gpgme/data.rb', line 189

def file_name
  GPGME::gpgme_data_get_file_name(self)
end

#file_name=(file_name) ⇒ Object

Sets the file name for this buffer.

Raises:



197
198
199
200
201
202
 
# File 'lib/gpgme/data.rb', line 197

def file_name=(file_name)
  err = GPGME::gpgme_data_set_file_name(self, file_name)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  file_name
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"


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

#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"


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

#to_s ⇒ Object

Return the entire content of the data object as string.



206
207
208
209
210
211
212
213
214
 
# File 'lib/gpgme/data.rb', line 206

def to_s
  pos = seek(0, IO::SEEK_CUR)
  begin
    seek(0)
    read
  ensure
    seek(pos)
  end
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"


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

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