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.

API:

  • private

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:

  • (defaults to: nil)

    The data string wrapped by the byte buffer (optional)

  • (defaults to: nil)

    A pointer to an existing mongocrypt_binary_t object

API:

  • private



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

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:

  • A string to be wrapped by the Binary object

Returns:

  • A new binary object

API:

  • private



87
88
89
 
# File 'lib/mongo/crypt/binary.rb', line 87

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:

  • A pointer to an existing mongocrypt_binary_t object

Returns:

  • A new binary object

API:

  • private



76
77
78
 
# File 'lib/mongo/crypt/binary.rb', line 76

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.

API:

  • private



145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/mongo/crypt/binary.rb', line 145

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:

  • The underlying mongocrypt_binary_t object

API:

  • private



139
140
141
 
# File 'lib/mongo/crypt/binary.rb', line 139

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:

  • Data stored in the mongocrypt_binary_t as a string

API:

  • private



129
130
131
132
133
 
# File 'lib/mongo/crypt/binary.rb', line 129

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:

  • The new string data to be wrapped by this binary object

Returns:

  • Always true

Raises:

  • Raises when trying to write more data

API:

  • private



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

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