123456789_123456789_123456789_123456789_123456789_

Class: Mongo::Crypt::Binary Private

Relationships & Source Files
Inherits: Object
Defined in: lib/mongo/crypt/binary.rb

Overview

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

Instance Method Summary

Constructor Details

.new(data: nil, pointer: nil) ⇒ Binary

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) —

    The data string wrapped by the byte buffer (optional)

  • pointer (FFI::Pointer) —

    A pointer to an existing mongocrypt_binary_t object

[ GitHub ] 

  


# 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)  ⇒ Binary 
  



  

    
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:


    
  
  • 
    (Binary)
—    
    A new binary object
    
  
    • 





  [ GitHub ]


  

  


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



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


  








  

    .from_pointer(pointer)  ⇒ Binary 
  



  

    
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:


    
  
  • 
    (Binary)
—    
    A new binary object
    
  
    • 





  [ GitHub ]


  

  


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



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


  








  

    .wrap_string(str)  
  



  

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

  





  


  [ GitHub ]


  

  


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



def self.wrap_string(str)
  # mongocrypt_binary_new_from_data does not copy the buffer, so the
  # MemoryPointer must outlive the mongocrypt_binary_t. Hold it in a
  # local so it stays referenced for the whole method frame; otherwise
  # GC can free the buffer while libmongocrypt still points into it.
  data_p = FFI::MemoryPointer.from_string(str)
  binary_p = Binding.mongocrypt_binary_new_from_data(data_p, str.bytesize)
  begin
    yield binary_p
  ensure
    Binding.mongocrypt_binary_destroy(binary_p)
    data_p # rubocop:disable Lint/Void -- keep the buffer alive past destroy
  end
end


  







Instance Method Details



  

    #ref  ⇒ FFI::Pointer 
  



  

    
Returns the reference to the underlying mongocrypt_binary_t
object

  





  
Returns:


    
  
  • 
    (FFI::Pointer)
—    
    The underlying mongocrypt_binary_t object
    
  
    • 





  [ GitHub ]


  

  


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



def ref
  @bin
end


  








  

    #to_s  ⇒ String 
  



  

    
Returns the data stored as a string

  





  
Returns:


    
  
  • 
    (String)
—    
    Data stored in the mongocrypt_binary_t as a string
    
  
    • 





  [ GitHub ]


  

  


# 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 
  



  

    
  

    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
    
  
    • 





  [ GitHub ]


  

  


# 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