First pass on provider state implementation

[alilleybrinker]

No description provided.

[alilleybrinker]

This also includes removal of the old metadata stuff I'd forgotten to take out, which is why this commit shows as removing more lines than it adds.

I'm also reading up further on how to document things correctly in Doxygen. I think everything ought to include an error-handling section and a safety section.

[alilleybrinker]

This PR is ready for review now. It does a couple things:

1. Removes the old metadata implementation, which I guess I missed in my last PR.
2. Adds a mechanism to iterate over provider states of a Message, and then read the name and iterate over params for those provider states.

[alilleybrinker]

Here is the state of the pact_matching.h file now as well (for @djorgensen-mitre):

#ifndef pact_matching_ffi_h
#define pact_matching_ffi_h

/* Generated with cbindgen:0.13.2 */

/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

#ifdef __cplusplus
namespace pact_matching {
#endif // __cplusplus

/**
 * An enum representing the log level to use.
 *
 * This is exactly equivalent to `LevelFilter` from the `log` crate,
 * except that it's `#[repr(C)]`, meaning it's safe to put in the signature
 * of a C-exposed FFI function.
 */
typedef enum LevelFilter {
  LevelFilter_Off,
  LevelFilter_Error,
  LevelFilter_Warn,
  LevelFilter_Info,
  LevelFilter_Debug,
  LevelFilter_Trace,
} LevelFilter;

/**
 * Enum defining the pact specification versions supported by the library
 */
typedef enum PactSpecification {
  /**
   * Unknown or unsupported specification version
   */
  PactSpecification_Unknown,
  /**
   * First version of the pact specification (https://github.com/pact-foundation/pact-specification/tree/version-1)
   */
  PactSpecification_V1,
  /**
   * Second version of the pact specification (https://github.com/pact-foundation/pact-specification/tree/version-1.1)
   */
  PactSpecification_V1_1,
  /**
   * Version two of the pact specification (https://github.com/pact-foundation/pact-specification/tree/version-2)
   */
  PactSpecification_V2,
  /**
   * Version three of the pact specification (https://github.com/pact-foundation/pact-specification/tree/version-3)
   */
  PactSpecification_V3,
  /**
   * Version four of the pact specification (https://github.com/pact-foundation/pact-specification/tree/version-4)
   */
  PactSpecification_V4,
} PactSpecification;

/**
 * Struct that defines a message.
 */
typedef struct Message Message;

/**
 * An iterator that enables FFI iteration over metadata by putting all the keys on the heap
 * and tracking which one we're currently at.
 *
 * This assumes no mutation of the underlying metadata happens while the iterator is live.
 */
typedef struct MetadataIterator MetadataIterator;

/**
 * Struct that encapsulates all the info about a provider state
 */
typedef struct ProviderState ProviderState;

/**
 * Iterator over individual provider states.
 */
typedef struct ProviderStateIterator ProviderStateIterator;

/**
 * An iterator that enables FFI iteration over provider state params by putting all the keys on the heap
 * and tracking which one we're currently at.
 *
 * This assumes no mutation of the underlying provider state happens while the iterator is live.
 */
typedef struct ProviderStateParamIterator ProviderStateParamIterator;

/**
 * A single key-value pair exported to the C-side.
 */
typedef struct MetadataPair {
  const char *key;
  const char *value;
} MetadataPair;

/**
 * A single key-value pair exported to the C-side.
 */
typedef struct ProviderStateParamPair {
  const char *key;
  const char *value;
} ProviderStateParamPair;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * Provide the error message from `LAST_ERROR` to the calling C code.
 *
 * # Params
 *
 * * `buffer`: a pointer to an array of `char` of sufficient length to hold the error message.
 * * `length`: an int providing the length of the `buffer`.
 *
 * # Return Codes
 *
 * * The number of bytes written to the provided buffer, which may be zero if there is no last error.
 * * `-1` if the provided buffer is a null pointer.
 * * `-2` if the provided buffer length is too small for the error message.
 * * `-3` if the write failed for some other reason.
 * * `-4` if the error message had an interior NULL
 *
 * # Notes
 *
 * Note that this function zeroes out any excess in the provided buffer.
 */
int get_error_message(char *buffer,
                      int length);

/**
 * Initialize the thread-local logger with no sinks.
 *
 * This initialized logger does nothing until `logger_apply` has been called.
 */
void logger_init(void);

/**
 * Attach an additional sink to the thread-local logger.
 *
 * This logger does nothing until `logger_apply` has been called.
 */
int logger_attach_sink(const char *sink_specifier, LevelFilter level_filter);

/**
 * Apply the thread-local logger to the program.
 *
 * Any attempts to modify the logger after the call to `logger_apply` will fail.
 */
int logger_apply(void);

/**
 * Get a mutable pointer to a newly-created default message on the heap.
 */
Message *message_new(void);

/**
 * Constructs a `Message` from the JSON string
 */
Message *message_new_from_json(unsigned int index,
                               const char *json_str,
                               PactSpecification spec_version);

/**
 * Destroy the `Message` being pointed to.
 */
int message_delete(Message *message);

/**
 * Get a copy of the description.
 * The returned string must be deleted with `string_delete`.
 *
 * Since it is a copy, the returned string may safely outlive
 * the `Message`.
 *
 * # Errors
 *
 * On failure, this function will return a NULL pointer.
 *
 * This function may fail if the Rust string contains embedded
 * null ('\0') bytes.
 */
const char *message_get_description(const Message *message);

/**
 * Write the `description` field on the `Message`.
 *
 * `description` must contain valid UTF-8. Invalid UTF-8
 * will be replaced with U+FFFD REPLACEMENT CHARACTER.
 *
 * This function will only reallocate if the new string
 * does not fit in the existing buffer.
 */
int message_set_description(Message *message, const char *description);

/**
 * Get a copy of the provider state at the given index from this message.
 * A pointer to the structure will be written to `out_provider_state`,
 * only if no errors are encountered.
 *
 * The returned structure must be deleted with `provider_state_delete`.
 *
 * Since it is a copy, the returned structure may safely outlive
 * the `Message`.
 *
 * # Errors
 *
 * On failure, this function will return a variant other than Success.
 *
 * This function may fail if the index requested is out of bounds,
 * or if any of the Rust strings contain embedded null ('\0') bytes.
 */
const ProviderState *message_get_provider_state(const Message *message, uintptr_t index);

/**
 * Get an iterator over provider states.
 */
ProviderStateIterator *message_get_provider_state_iter(Message *message);

/**
 * Get the next value from the iterator.
 */
ProviderState *provider_state_iter_next(ProviderStateIterator *iter);

/**
 * Delete the iterator.
 */
int provider_state_iter_delete(ProviderStateIterator *iter);

/**
 * Get a copy of the metadata value indexed by `key`.
 * The returned string must be deleted with `string_delete`.
 *
 * Since it is a copy, the returned string may safely outlive
 * the `Message`.
 *
 * The returned pointer will be NULL if the metadata does not contain
 * the given key, or if an error occurred.
 *
 * # Errors
 *
 * On failure, this function will return a NULL pointer.
 *
 * This function may fail if the provided `key` string contains
 * invalid UTF-8, or if the Rust string contains embedded null ('\0')
 * bytes.
 */
const char *message_find_metadata(const Message *message, const char *key);

/**
 * Insert the (`key`, `value`) pair into this Message's
 * `metadata` HashMap.
 * This function returns an enum indicating the result;
 * see the comments on HashMapInsertStatus for details.
 *
 * # Errors
 *
 * This function may fail if the provided `key` or `value` strings
 * contain invalid UTF-8.
 */
int message_insert_metadata(Message *message, const char *key, const char *value);

/**
 * Get an iterator over the metadata of a message.
 *
 * This iterator carries a pointer to the message, and must
 * not outlive the message.
 *
 * The message metadata also must not be modified during iteration. If it is,
 * the old iterator must be deleted and a new iterator created.
 *
 * # Errors
 *
 * On failure, this function will return a NULL pointer.
 *
 * This function may fail if any of the Rust strings contain
 * embedded null ('\0') bytes.
 */
MetadataIterator *message_get_metadata_iter(Message *message);

/**
 * Get the next key and value out of the iterator, if possible
 *
 * Returns a pointer to a heap allocated array of 2 elements, the pointer to the
 * key string on the heap, and the pointer to the value string on the heap.
 *
 * The user needs to free both the contained strings and the array.
 */
MetadataPair *metadata_iter_next(MetadataIterator *iter);

/**
 * Free the metadata iterator when you're done using it.
 */
int metadata_iter_delete(MetadataIterator *iter);

/**
 * Free a pair of key and value returned from `message_next_metadata_iter`.
 */
int metadata_pair_delete(MetadataPair *pair);

/**
 * Get the name of the provider state as a string, which needs to be deleted with `string_delete`.
 */
const char *provider_state_get_name(const ProviderState *provider_state);

/**
 * Get an iterator over the params of a provider state.
 *
 * This iterator carries a pointer to the provider state, and must
 * not outlive the provider state.
 *
 * The provider state params also must not be modified during iteration. If it is,
 * the old iterator must be deleted and a new iterator created.
 *
 * # Errors
 *
 * On failure, this function will return a NULL pointer.
 *
 * This function may fail if any of the Rust strings contain
 * embedded null ('\0') bytes.
 */
ProviderStateParamIterator *provider_state_get_param_iter(ProviderState *provider_state);

/**
 * Get the next key and value out of the iterator, if possible
 *
 * Returns a pointer to a heap allocated array of 2 elements, the pointer to the
 * key string on the heap, and the pointer to the value string on the heap.
 *
 * The user needs to free both the contained strings and the array.
 */
ProviderStateParamPair *provider_state_param_iter_next(ProviderStateParamIterator *iter);

/**
 * Free the provider state param iterator when you're done using it.
 */
int provider_state_param_iter_delete(ProviderStateParamIterator *iter);

/**
 * Free a pair of key and value returned from `provider_state_param_iter_next`.
 */
int provider_state_param_pair_delete(ProviderStateParamPair *pair);

/**
 * Delete a string previously returned by this FFI.
 *
 * It is explicitly allowed to pass a null pointer to this function;
 * in that case the function will do nothing.
 */
void string_delete(char *string);

#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus

#ifdef __cplusplus
} // namespace pact_matching
#endif // __cplusplus

#endif /* pact_matching_ffi_h */