Class: Mongo::Crypt::Binary Private

Inherits:
Object
  • Object
show all
Defined in:
lib/mongo/crypt/binary.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

A wrapper around mongocrypt_binary_t, a non-owning buffer of uint-8 byte data. Each Binary instance keeps a copy of the data passed to it in order to keep that data alive.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data: nil, pointer: nil) ⇒ Binary

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

When initializing a Binary object with a string or a pointer,

Create a new Binary object that wraps a byte string

it is recommended that you use #self.from_pointer or #self.from_data methods

Parameters:

  • data (String) (defaults to: nil) —

    The data string wrapped by the byte buffer (optional)

  • pointer (FFI::Pointer) (defaults to: nil) —

    A pointer to an existing mongocrypt_binary_t object



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/mongo/crypt/binary.rb', line 36

def initialize(data: nil, pointer: nil)
  if data
    # Represent data string as array of uint-8 bytes
    bytes = data.unpack('C*')

    # FFI::MemoryPointer automatically frees memory when it goes out of scope
    @data_p = FFI::MemoryPointer.new(bytes.length)
              .write_array_of_uint8(bytes)

    # FFI::AutoPointer uses a custom release strategy to automatically free
    # the pointer once this object goes out of scope
    @bin = FFI::AutoPointer.new(
      Binding.mongocrypt_binary_new_from_data(@data_p, bytes.length),
      Binding.method(:mongocrypt_binary_destroy)
    )
  elsif pointer
    # If the Binary class is used this way, it means that the pointer
    # for the underlying mongocrypt_binary_t object is allocated somewhere
    # else. It is not the responsibility of this class to de-allocate data.
    @bin = pointer
  else
    # FFI::AutoPointer uses a custom release strategy to automatically free
    # the pointer once this object goes out of scope
    @bin = FFI::AutoPointer.new(
      Binding.mongocrypt_binary_new,
      Binding.method(:mongocrypt_binary_destroy)
    )
  end
end

Class Method Details

.from_data(data) ⇒ Mongo::Crypt::Binary

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize a Binary object with a string. The Binary object will store a copy of the specified string and destroy the allocated memory when it goes out of scope.

Parameters:

  • data (String) —

    A string to be wrapped by the Binary object

Returns:



84
85
86
 
# File 'lib/mongo/crypt/binary.rb', line 84

def self.from_data(data)
  self.new(data: data)
end

.from_pointer(pointer) ⇒ Mongo::Crypt::Binary

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize a Binary object from an existing pointer to a mongocrypt_binary_t object.

Parameters:

  • pointer (FFI::Pointer) —

    A pointer to an existing mongocrypt_binary_t object

Returns:



73
74
75
 
# File 'lib/mongo/crypt/binary.rb', line 73

def self.from_pointer(pointer)
  self.new(pointer: pointer)
end

.wrap_string(str) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Wraps a String with a mongocrypt_binary_t, yielding an FFI::Pointer to the wrapped struct.



142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/mongo/crypt/binary.rb', line 142

def self.wrap_string(str)
  binary_p = Binding.mongocrypt_binary_new_from_data(
    FFI::MemoryPointer.from_string(str),
    str.bytesize,
  )
  begin
    yield binary_p
  ensure
    Binding.mongocrypt_binary_destroy(binary_p)
  end
end

Instance Method Details

#ref ⇒ FFI::Pointer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the reference to the underlying mongocrypt_binary_t object

Returns:

  • (FFI::Pointer) —

    The underlying mongocrypt_binary_t object



136
137
138
 
# File 'lib/mongo/crypt/binary.rb', line 136

def ref
  @bin
end

#to_s ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the data stored as a string

Returns:

  • (String) —

    Data stored in the mongocrypt_binary_t as a string



126
127
128
129
130
 
# File 'lib/mongo/crypt/binary.rb', line 126

def to_s
  str_p = Binding.mongocrypt_binary_data(ref)
  len = Binding.mongocrypt_binary_len(ref)
  str_p.read_string(len)
end

#write(data) ⇒ true

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

The data passed in must not take up more memory than the

Overwrite the existing data wrapped by this Binary object

original memory allocated to the underlying mongocrypt_binary_t object. Do NOT use this method unless required to do so by libmongocrypt.

than was originally allocated or when writing to an object that already owns data.

Parameters:

  • data (String) —

    The new string data to be wrapped by this binary object

Returns:

  • (true) —

    Always true

Raises:

  • (ArgumentError) —

    Raises when trying to write more data



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/mongo/crypt/binary.rb', line 101

def write(data)
  if @data
    raise ArgumentError, 'Cannot write to an owned Binary'
  end

  # Cannot write a string that's longer than the space currently allocated
  # by the mongocrypt_binary_t object
  str_p = Binding.mongocrypt_binary_data(ref)
  len = Binding.mongocrypt_binary_len(ref)

  if len < data.bytesize
    raise ArgumentError.new(
      "Cannot write #{data.bytesize} bytes of data to a Binary object " +
      "that was initialized with #{Binding.mongocrypt_binary_len(@bin)} bytes."
    )
  end

  str_p.put_bytes(0, data)

  true
end