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



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:

  • data (String) —

    A string to be wrapped by the Binary object

Returns:



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:

  • pointer (FFI::Pointer) —

    A pointer to an existing mongocrypt_binary_t object

Returns:



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.



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:

  • (FFI::Pointer) —

    The underlying mongocrypt_binary_t object



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:

  • (String) —

    Data stored in the mongocrypt_binary_t as a string



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:

  • 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



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