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



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
65
 
# File 'lib/mongo/crypt/binary.rb', line 37

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:



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

def self.from_data(data)
  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:



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

def self.from_pointer(pointer)
  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.



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

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



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

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



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

def to_s
  str_p = Binding.get_binary_data_direct(ref)
  len = Binding.get_binary_len_direct(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



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

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

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

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

  str_p.put_bytes(0, data)

  true
end