class Mongo::Crypt::Status

A wrapper around mongocrypt_status_t, representing the status of a mongocrypt_t handle.

@api private

Public Class Methods

from_pointer(pointer) click to toggle source

Initialize a Status object from an existing pointer to a mongocrypt_status_t object.

@param [ FFI::Pointer ] pointer A pointer to an existing

mongocrypt_status_t object

@return [ Mongo::Crypt::Status ] A new Status object

# File lib/mongo/crypt/status.rb, line 53
def self.from_pointer(pointer)
  self.new(pointer: pointer)
end
new(pointer: nil) click to toggle source

Create a new Status object

@param [ FFI::Pointer | nil ] pointer A pointer to an existing

mongocrypt_status_t object. Defaults to nil.

@note When initializing a Status object with a pointer, it is recommended that you use the self.from_pointer method

# File lib/mongo/crypt/status.rb, line 34
def initialize(pointer: nil)
  # If a pointer is passed in, this class is not responsible for
  # destroying that pointer and deallocating data.
  #
  # FFI::AutoPointer uses a custom release strategy to automatically free
  # the pointer once this object goes out of scope
  @status = pointer || FFI::AutoPointer.new(
                        Binding.mongocrypt_status_new,
                        Binding.method(:mongocrypt_status_destroy)
                      )
end

Public Instance Methods

code() click to toggle source

Return the integer code associated with the status

@return [ Integer ] The status code, defaults to 0

# File lib/mongo/crypt/status.rb, line 89
def code
  Binding.mongocrypt_status_code(@status)
end
label() click to toggle source

Return the label of the status

@return [ Symbol ] The status label, either :ok, :error_kms, or :error_client,

defaults to :ok
# File lib/mongo/crypt/status.rb, line 82
def label
  Binding.mongocrypt_status_type(@status)
end
message() click to toggle source

Return the status message

@return [ String ] The status message, defaults to empty string

# File lib/mongo/crypt/status.rb, line 96
def message
  message = Binding.mongocrypt_status_message(@status, nil)
  message || ''
end
ok?() click to toggle source

Checks whether the status is labeled :ok

@return [ Boolean ] Whether the status is :ok

# File lib/mongo/crypt/status.rb, line 104
def ok?
  Binding.mongocrypt_status_ok(@status)
end
raise_crypt_error(kms: false) click to toggle source

Raises a Mongo::Error:CryptError corresponding to the information stored in this status

Does nothing if self.ok? is true

@param kms [ true | false ] Whether the operation was against the KMS.

@note If kms parameter is false, the error may still have come from a

KMS. The kms parameter simply forces all errors to be treated as
KMS errors.
# File lib/mongo/crypt/status.rb, line 126
def raise_crypt_error(kms: false)
  return if ok?

  if kms || label == :error_kms
    error = Error::KmsError.new(message, code: code)
  else
    error = Error::CryptError.new(message, code: code)
  end

  raise error
end
ref() click to toggle source

Returns the reference to the underlying mongocrypt_status_t object

@return [ FFI::Pointer ] Pointer to the underlying mongocrypt_status_t oject

# File lib/mongo/crypt/status.rb, line 112
def ref
  @status
end
update(label, code, message) click to toggle source

Set a label, code, and message on the Status

@param [ Symbol ] label One of :ok, :error_client, or :error_kms @param [ Integer ] code @param [ String ] message

@return [ Mongo::Crypt::Status ] returns self

# File lib/mongo/crypt/status.rb, line 64
def update(label, code, message)
  unless [:ok, :error_client, :error_kms].include?(label)
    raise ArgumentError.new(
      "#{label} is an invalid value for a Mongo::Crypt::Status label. " +
      "Label must have one of the following values: :ok, :error_client, :error_kms"
    )
  end

  message_length = message ? message.bytesize + 1 : 0
  Binding.mongocrypt_status_set(@status, label, code, message, message_length)

  self
end