@pact-foundation/pact-core 13.5.1 → 13.6.0

package/ffi/{v0.0.3-pact.h → pact.h}

@@ -128,6 +128,16 @@ typedef struct Mismatches Mismatches;
  */
 typedef struct MismatchesIterator MismatchesIterator;
 
+/**
+ * An iterator over messages in a pact.
+ */
+typedef struct PactMessageIterator PactMessageIterator;
+
+/**
+ * An iterator over synchronous request/response messages in a pact.
+ */
+typedef struct PactSyncMessageIterator PactSyncMessageIterator;
+
 /**
  * Struct that defines a provider of a pact.
  */
@@ -151,6 +161,11 @@ typedef struct ProviderStateIterator ProviderStateIterator;
  */
 typedef struct ProviderStateParamIterator ProviderStateParamIterator;
 
+/**
+ * Synchronous interactions as a request message to a sequence of response messages
+ */
+typedef struct SynchronousMessage SynchronousMessage;
+
 /**
  * Wraps a Pact verifier
  */
@@ -205,26 +220,7 @@ typedef struct ProviderStateParamPair {
 /**
  * Wraps a Pact model struct
  */
-typedef struct PactHandle {
-  /**
-   * Pact reference
-   */
-  uintptr_t pact;
-} PactHandle;
-
-/**
- * Wraps a Pact model struct
- */
-typedef struct InteractionHandle {
-  /**
-   * Pact reference
-   */
-  uintptr_t pact;
-  /**
-   * Interaction reference
-   */
-  uintptr_t interaction;
-} InteractionHandle;
+typedef uint16_t PactHandle;
 
 /**
  * Result of wrapping a string value
@@ -255,26 +251,17 @@ typedef struct StringResult {
 /**
  * Wraps a Pact model struct
  */
-typedef struct MessagePactHandle {
-  /**
-   * Pact reference
-   */
-  uintptr_t pact;
-} MessagePactHandle;
+typedef uint32_t InteractionHandle;
 
 /**
  * Wraps a Pact model struct
  */
-typedef struct MessageHandle {
-  /**
-   * Message Pact reference
-   */
-  uintptr_t pact;
-  /**
-   * Interaction reference
-   */
-  uintptr_t message;
-} MessageHandle;
+typedef uint16_t MessagePactHandle;
+
+/**
+ * Wraps a Pact model struct
+ */
+typedef uint32_t MessageHandle;
 
 /**
  * Get the current library version
@@ -287,7 +274,7 @@ const char *pactffi_version(void);
  *
  * # Safety
  *
- * Exported functions are inherently unsafe.
+ * log_env_var must be a valid NULL terminated UTF-8 string.
  */
 void pactffi_init(const char *log_env_var);
 
@@ -300,6 +287,15 @@ void pactffi_init(const char *log_env_var);
  */
 void pactffi_init_with_log_level(const char *level);
 
+/**
+ * Enable ANSI coloured output on Windows. On non-Windows platforms, this function is a no-op.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ */
+void pactffi_enable_ansi_support(void);
+
 /**
  * Log using the shared core logging facility.
  *
@@ -597,7 +593,7 @@ struct Message *pactffi_message_new_from_body(const char *body, const char *cont
 void pactffi_message_delete(struct Message *message);
 
 /**
- * Get the contents of a `Message`.
+ * Get the contents of a `Message` in string form.
  *
  * # Safety
  *
@@ -614,6 +610,36 @@ void pactffi_message_delete(struct Message *message);
  */
 const char *pactffi_message_get_contents(const struct Message *message);
 
+/**
+ * Get the length of the contents of a `Message`.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * # Error Handling
+ *
+ * If the message is NULL, returns 0. If the body of the message
+ * is missing, then this function also returns 0.
+ */
+size_t pactffi_message_get_contents_length(const struct Message *message);
+
+/**
+ * Get the contents of a `Message` as a pointer to an array of bytes.
+ *
+ * # Safety
+ *
+ * The number of bytes in the buffer will be returned by `pactffi_message_get_contents_length`.
+ * It is safe to use the pointer while the message is not deleted or changed. Using the pointer
+ * after the message is mutated or deleted may lead to undefined behaviour.
+ *
+ * # Error Handling
+ *
+ * If the message is NULL, returns NULL. If the body of the message
+ * is missing, then this function also returns NULL.
+ */
+const unsigned char *pactffi_message_get_contents_bin(const struct Message *message);
+
 /**
  * Get a copy of the description.
  *
@@ -690,6 +716,9 @@ struct ProviderStateIterator *pactffi_message_get_provider_state_iter(struct Mes
  *
  * The underlying data must not change during iteration.
  *
+ * If a previous call panicked, then the internal mutex will have been poisoned and this
+ * function will return NULL.
+ *
  * # Error Handling
  *
  * Returns NULL if an error occurs.
@@ -1045,6 +1074,238 @@ void pactffi_provider_state_param_iter_delete(struct ProviderStateParamIterator
  */
 void pactffi_provider_state_param_pair_delete(struct ProviderStateParamPair *pair);
 
+/**
+ * Free the iterator when you're done using it.
+ */
+void pactffi_pact_message_iter_delete(struct PactMessageIterator *iter);
+
+/**
+ * Get the next message from the message pact. As the messages returned are owned by the
+ * iterator, they do not need to be deleted but will be cleaned up when the iterator is
+ * deleted.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * Deleting a message returned by the iterator can lead to undefined behaviour.
+ *
+ * # Error Handling
+ *
+ * This function will return a NULL pointer if passed a NULL pointer or if an error occurs.
+ */
+struct Message *pactffi_pact_message_iter_next(struct PactMessageIterator *iter);
+
+/**
+ * Get the next synchronous request/response message from the pact. As the messages returned are owned by the
+ * iterator, they do not need to be deleted but will be cleaned up when the iterator is
+ * deleted.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * Deleting a message returned by the iterator can lead to undefined behaviour.
+ *
+ * # Error Handling
+ *
+ * This function will return a NULL pointer if passed a NULL pointer or if an error occurs.
+ */
+struct SynchronousMessage *pactffi_pact_sync_message_iter_next(struct PactSyncMessageIterator *iter);
+
+/**
+ * Free the iterator when you're done using it.
+ */
+void pactffi_pact_sync_message_iter_delete(struct PactSyncMessageIterator *iter);
+
+/**
+ * Destroy the `Message` being pointed to.
+ */
+void pactffi_sync_message_delete(struct SynchronousMessage *message);
+
+/**
+ * Get the request contents of a `SynchronousMessage` in string form.
+ *
+ * # Safety
+ *
+ * The returned string must be deleted with `pactffi_string_delete`.
+ *
+ * The returned string can outlive the message.
+ *
+ * # Error Handling
+ *
+ * If the message is NULL, returns NULL. If the body of the request message
+ * is missing, then this function also returns NULL. This means there's
+ * no mechanism to differentiate with this function call alone between
+ * a NULL message and a missing message body.
+ */
+const char *pactffi_sync_message_get_request_contents(const struct SynchronousMessage *message);
+
+/**
+ * Get the length of the request contents of a `SynchronousMessage`.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * # Error Handling
+ *
+ * If the message is NULL, returns 0. If the body of the request
+ * is missing, then this function also returns 0.
+ */
+size_t pactffi_sync_message_get_request_contents_length(const struct SynchronousMessage *message);
+
+/**
+ * Get the request contents of a `SynchronousMessage` as a pointer to an array of bytes.
+ *
+ * # Safety
+ *
+ * The number of bytes in the buffer will be returned by `pactffi_sync_message_get_request_contents_length`.
+ * It is safe to use the pointer while the message is not deleted or changed. Using the pointer
+ * after the message is mutated or deleted may lead to undefined behaviour.
+ *
+ * # Error Handling
+ *
+ * If the message is NULL, returns NULL. If the body of the message
+ * is missing, then this function also returns NULL.
+ */
+const unsigned char *pactffi_sync_message_get_request_contents_bin(const struct SynchronousMessage *message);
+
+/**
+ * Get the number of response messages in the `SynchronousMessage`.
+ *
+ * # Safety
+ *
+ * The message pointer must point to a valid SynchronousMessage.
+ *
+ * # Error Handling
+ *
+ * If the message is NULL, returns 0.
+ */
+size_t pactffi_sync_message_get_number_responses(const struct SynchronousMessage *message);
+
+/**
+ * Get the response contents of a `SynchronousMessage` in string form.
+ *
+ * # Safety
+ *
+ * The returned string must be deleted with `pactffi_string_delete`.
+ *
+ * The returned string can outlive the message.
+ *
+ * # Error Handling
+ *
+ * If the message is NULL or the index is not valid, returns NULL.
+ *
+ * If the body of the response message is missing, then this function also returns NULL.
+ * This means there's no mechanism to differentiate with this function call alone between
+ * a NULL message and a missing message body.
+ */
+const char *pactffi_sync_message_get_response_contents(const struct SynchronousMessage *message,
+                                                       size_t index);
+
+/**
+ * Get the length of the response contents of a `SynchronousMessage`.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * # Error Handling
+ *
+ * If the message is NULL or the index is not valid, returns 0. If the body of the request
+ * is missing, then this function also returns 0.
+ */
+size_t pactffi_sync_message_get_response_contents_length(const struct SynchronousMessage *message,
+                                                         size_t index);
+
+/**
+ * Get the response contents of a `SynchronousMessage` as a pointer to an array of bytes.
+ *
+ * # Safety
+ *
+ * The number of bytes in the buffer will be returned by `pactffi_sync_message_get_response_contents_length`.
+ * It is safe to use the pointer while the message is not deleted or changed. Using the pointer
+ * after the message is mutated or deleted may lead to undefined behaviour.
+ *
+ * # Error Handling
+ *
+ * If the message is NULL or the index is not valid, returns NULL. If the body of the message
+ * is missing, then this function also returns NULL.
+ */
+const unsigned char *pactffi_sync_message_get_response_contents_bin(const struct SynchronousMessage *message,
+                                                                    size_t index);
+
+/**
+ * Get a copy of the description.
+ *
+ * # Safety
+ *
+ * The returned string must be deleted with `pactffi_string_delete`.
+ *
+ * Since it is a copy, the returned string may safely outlive
+ * the `SynchronousMessage`.
+ *
+ * # 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 *pactffi_sync_message_get_description(const struct SynchronousMessage *message);
+
+/**
+ * Write the `description` field on the `SynchronousMessage`.
+ *
+ * # Safety
+ *
+ * `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.
+ *
+ * # Error Handling
+ *
+ * Errors will be reported with a non-zero return value.
+ */
+int pactffi_sync_message_set_description(struct SynchronousMessage *message,
+                                         const char *description);
+
+/**
+ * Get a copy of the provider state at the given index from this message.
+ *
+ * # Safety
+ *
+ * The returned structure must be deleted with `provider_state_delete`.
+ *
+ * Since it is a copy, the returned structure may safely outlive
+ * the `SynchronousMessage`.
+ *
+ * # Error Handling
+ *
+ * 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 struct ProviderState *pactffi_sync_message_get_provider_state(const struct SynchronousMessage *message,
+                                                                    unsigned int index);
+
+/**
+ * Get an iterator over provider states.
+ *
+ * # Safety
+ *
+ * The underlying data must not change during iteration.
+ *
+ * # Error Handling
+ *
+ * Returns NULL if an error occurs.
+ */
+struct ProviderStateIterator *pactffi_sync_message_get_provider_state_iter(struct SynchronousMessage *message);
+
 /**
  * Delete a string previously returned by this FFI.
  *
@@ -1114,7 +1375,7 @@ char *pactffi_get_tls_ca_certificate(void);
  * | -6 | Could not create the TLS configuration with the self-signed certificate |
  *
  */
-int32_t pactffi_create_mock_server_for_pact(struct PactHandle pact,
+int32_t pactffi_create_mock_server_for_pact(PactHandle pact,
                                             const char *addr_str,
                                             bool tls);
 
@@ -1182,24 +1443,81 @@ int32_t pactffi_write_pact_file(int32_t mock_server_port, const char *directory,
  */
 const char *pactffi_mock_server_logs(int32_t mock_server_port);
 
+/**
+ * Generates a datetime value from the provided format string, using the current system date and time
+ * NOTE: The memory for the returned string needs to be freed with the free_string function
+ *
+ * # Safety
+ *
+ * Exported functions are inherently unsafe.
+ */
+struct StringResult pactffi_generate_datetime_string(const char *format);
+
+/**
+ * Checks that the example string matches the given regex
+ *
+ * # Safety
+ *
+ * Exported functions are inherently unsafe.
+ */
+bool pactffi_check_regex(const char *regex, const char *example);
+
+/**
+ * Generates an example string based on the provided regex.
+ * NOTE: The memory for the returned string needs to be freed with the free_string function
+ *
+ * # Safety
+ *
+ * Exported functions are inherently unsafe.
+ */
+struct StringResult pactffi_generate_regex_value(const char *regex);
+
+/**
+ * [DEPRECATED] Frees the memory allocated to a string by another function
+ *
+ * This function is deprecated. Use pactffi_string_delete instead.
+ *
+ * # Safety
+ *
+ * Exported functions are inherently unsafe.
+ */
+void pactffi_free_string(char *s);
+
 /**
  * Creates a new Pact model and returns a handle to it.
  *
  * * `consumer_name` - The name of the consumer for the pact.
  * * `provider_name` - The name of the provider for the pact.
  *
- * Returns a new `PactHandle`.
+ * Returns a new `PactHandle`. The handle will need to be freed with the `pactffi_free_pact_handle`
+ * method to release its resources.
  */
-struct PactHandle pactffi_new_pact(const char *consumer_name, const char *provider_name);
+PactHandle pactffi_new_pact(const char *consumer_name, const char *provider_name);
 
 /**
- * Creates a new Interaction and returns a handle to it.
+ * Creates a new HTTP Interaction and returns a handle to it.
  *
  * * `description` - The interaction description. It needs to be unique for each interaction.
  *
  * Returns a new `InteractionHandle`.
  */
-struct InteractionHandle pactffi_new_interaction(struct PactHandle pact, const char *description);
+InteractionHandle pactffi_new_interaction(PactHandle pact, const char *description);
+
+/**
+ * Creates a new message interaction and return a handle to it
+ * * `description` - The interaction description. It needs to be unique for each interaction.
+ *
+ * Returns a new `InteractionHandle`.
+ */
+InteractionHandle pactffi_new_message_interaction(PactHandle pact, const char *description);
+
+/**
+ * Creates a new synchronous message interaction (request/response) and return a handle to it
+ * * `description` - The interaction description. It needs to be unique for each interaction.
+ *
+ * Returns a new `InteractionHandle`.
+ */
+InteractionHandle pactffi_new_sync_message_interaction(PactHandle pact, const char *description);
 
 /**
  * Sets the description for the Interaction. Returns false if the interaction or Pact can't be
@@ -1207,7 +1525,7 @@ struct InteractionHandle pactffi_new_interaction(struct PactHandle pact, const c
  *
  * * `description` - The interaction description. It needs to be unique for each interaction.
  */
-bool pactffi_upon_receiving(struct InteractionHandle interaction, const char *description);
+bool pactffi_upon_receiving(InteractionHandle interaction, const char *description);
 
 /**
  * Adds a provider state to the Interaction. Returns false if the interaction or Pact can't be
@@ -1215,7 +1533,27 @@ bool pactffi_upon_receiving(struct InteractionHandle interaction, const char *de
  *
  * * `description` - The provider state description. It needs to be unique.
  */
-bool pactffi_given(struct InteractionHandle interaction, const char *description);
+bool pactffi_given(InteractionHandle interaction, const char *description);
+
+/**
+ * Sets the test name annotation for the interaction. This allows capturing the name of
+ * the test as metadata. This can only be used with V4 interactions.
+ *
+ * # Safety
+ *
+ * The test name parameter must be a valid pointer to a NULL terminated string.
+ *
+ * # Error Handling
+ *
+ * If the test name can not be set, this will return a positive value.
+ *
+ * * `1` - Function panicked. Error message will be available by calling `pactffi_get_error_message`.
+ * * `2` - Handle was not valid.
+ * * `3` - Mock server was already started and the interation can not be modified.
+ * * `4` - Not a V4 interaction.
+ */
+unsigned int pactffi_interaction_test_name(InteractionHandle interaction,
+                                           const char *test_name);
 
 /**
  * Adds a provider state to the Interaction with a parameter key and value. Returns false if the interaction or Pact can't be
@@ -1225,7 +1563,7 @@ bool pactffi_given(struct InteractionHandle interaction, const char *description
  * * `name` - Parameter name.
  * * `value` - Parameter value.
  */
-bool pactffi_given_with_param(struct InteractionHandle interaction,
+bool pactffi_given_with_param(InteractionHandle interaction,
                               const char *description,
                               const char *name,
                               const char *value);
@@ -1237,9 +1575,7 @@ bool pactffi_given_with_param(struct InteractionHandle interaction,
  * * `method` - The request method. Defaults to GET.
  * * `path` - The request path. Defaults to `/`.
  */
-bool pactffi_with_request(struct InteractionHandle interaction,
-                          const char *method,
-                          const char *path);
+bool pactffi_with_request(InteractionHandle interaction, const char *method, const char *path);
 
 /**
  * Configures a query parameter for the Interaction. Returns false if the interaction or Pact can't be
@@ -1249,7 +1585,7 @@ bool pactffi_with_request(struct InteractionHandle interaction,
  * * `value` - the query parameter value.
  * * `index` - the index of the value (starts at 0). You can use this to create a query parameter with multiple values
  */
-bool pactffi_with_query_parameter(struct InteractionHandle interaction,
+bool pactffi_with_query_parameter(InteractionHandle interaction,
                                   const char *name,
                                   size_t index,
                                   const char *value);
@@ -1261,7 +1597,7 @@ bool pactffi_with_query_parameter(struct InteractionHandle interaction,
  * * `pact` - Handle to a Pact model
  * * `version` - the spec version to use
  */
-bool pactffi_with_specification(struct PactHandle pact,
+bool pactffi_with_specification(PactHandle pact,
                                 enum PactSpecification version);
 
 /**
@@ -1273,7 +1609,7 @@ bool pactffi_with_specification(struct PactHandle pact,
  * * `name` - the key to set
  * * `value` - the value to set
  */
-bool pactffi_with_pact_metadata(struct PactHandle pact,
+bool pactffi_with_pact_metadata(PactHandle pact,
                                 const char *namespace_,
                                 const char *name,
                                 const char *value);
@@ -1287,7 +1623,7 @@ bool pactffi_with_pact_metadata(struct PactHandle pact,
  * * `value` - the header value.
  * * `index` - the index of the value (starts at 0). You can use this to create a header with multiple values
  */
-bool pactffi_with_header(struct InteractionHandle interaction,
+bool pactffi_with_header(InteractionHandle interaction,
                          enum InteractionPart part,
                          const char *name,
                          size_t index,
@@ -1299,7 +1635,7 @@ bool pactffi_with_header(struct InteractionHandle interaction,
  *
  * * `status` - the response status. Defaults to 200.
  */
-bool pactffi_response_status(struct InteractionHandle interaction, unsigned short status);
+bool pactffi_response_status(InteractionHandle interaction, unsigned short status);
 
 /**
  * Adds the body for the interaction. Returns false if the interaction or Pact can't be
@@ -1310,49 +1646,11 @@ bool pactffi_response_status(struct InteractionHandle interaction, unsigned shor
  *   header is already set.
  * * `body` - The body contents. For JSON payloads, matching rules can be embedded in the body.
  */
-bool pactffi_with_body(struct InteractionHandle interaction,
+bool pactffi_with_body(InteractionHandle interaction,
                        enum InteractionPart part,
                        const char *content_type,
                        const char *body);
 
-/**
- * Generates a datetime value from the provided format string, using the current system date and time
- * NOTE: The memory for the returned string needs to be freed with the free_string function
- *
- * # Safety
- *
- * Exported functions are inherently unsafe.
- */
-struct StringResult pactffi_generate_datetime_string(const char *format);
-
-/**
- * Checks that the example string matches the given regex
- *
- * # Safety
- *
- * Exported functions are inherently unsafe.
- */
-bool pactffi_check_regex(const char *regex, const char *example);
-
-/**
- * Generates an example string based on the provided regex.
- * NOTE: The memory for the returned string needs to be freed with the free_string function
- *
- * # Safety
- *
- * Exported functions are inherently unsafe.
- */
-struct StringResult pactffi_generate_regex_value(const char *regex);
-
-/**
- * Frees the memory allocated to a string by another function
- *
- * # Safety
- *
- * Exported functions are inherently unsafe.
- */
-void pactffi_free_string(char *s);
-
 /**
  * Adds a binary file as the body with the expected content type and example contents. Will use
  * a mime type matcher to match the body. Returns false if the interaction or Pact can't be
@@ -1364,7 +1662,7 @@ void pactffi_free_string(char *s);
  * * `body` - example body contents in bytes
  * * `size` - number of bytes in the body
  */
-bool pactffi_with_binary_file(struct InteractionHandle interaction,
+bool pactffi_with_binary_file(InteractionHandle interaction,
                               enum InteractionPart part,
                               const char *content_type,
                               const uint8_t *body,
@@ -1381,22 +1679,57 @@ bool pactffi_with_binary_file(struct InteractionHandle interaction,
  * * `file` - path to the example file
  * * `part_name` - name for the mime part
  */
-struct StringResult pactffi_with_multipart_file(struct InteractionHandle interaction,
+struct StringResult pactffi_with_multipart_file(InteractionHandle interaction,
                                                 enum InteractionPart part,
                                                 const char *content_type,
                                                 const char *file,
                                                 const char *part_name);
 
+/**
+ * Get an iterator over all the messages of the Pact. The returned iterator needs to be
+ * freed with `pactffi_pact_message_iter_delete`.
+ *
+ * # Safety
+ *
+ * The iterator contains a copy of the Pact, so it is always safe to use.
+ *
+ * # Error Handling
+ *
+ * On failure, this function will return a NULL pointer.
+ *
+ * This function may fail if any of the Rust strings contain embedded
+ * null ('\0') bytes.
+ */
+struct PactMessageIterator *pactffi_pact_handle_get_message_iter(PactHandle pact);
+
+/**
+ * Get an iterator over all the synchronous request/response messages of the Pact.
+ * The returned iterator needs to be freed with `pactffi_pact_sync_message_iter_delete`.
+ *
+ * # Safety
+ *
+ * The iterator contains a copy of the Pact, so it is always safe to use.
+ *
+ * # Error Handling
+ *
+ * On failure, this function will return a NULL pointer.
+ *
+ * This function may fail if any of the Rust strings contain embedded
+ * null ('\0') bytes.
+ */
+struct PactSyncMessageIterator *pactffi_pact_handle_get_sync_message_iter(PactHandle pact);
+
 /**
  * Creates a new Pact Message model and returns a handle to it.
  *
  * * `consumer_name` - The name of the consumer for the pact.
  * * `provider_name` - The name of the provider for the pact.
  *
- * Returns a new `MessagePactHandle`.
+ * Returns a new `MessagePactHandle`. The handle will need to be freed with the `pactffi_free_message_pact_handle`
+ * function to release its resources.
  */
-struct MessagePactHandle pactffi_new_message_pact(const char *consumer_name,
-                                                  const char *provider_name);
+MessagePactHandle pactffi_new_message_pact(const char *consumer_name,
+                                           const char *provider_name);
 
 /**
  * Creates a new Message and returns a handle to it.
@@ -1405,21 +1738,21 @@ struct MessagePactHandle pactffi_new_message_pact(const char *consumer_name,
  *
  * Returns a new `MessageHandle`.
  */
-struct MessageHandle pactffi_new_message(struct MessagePactHandle pact, const char *description);
+MessageHandle pactffi_new_message(MessagePactHandle pact, const char *description);
 
 /**
  * Sets the description for the Message.
  *
  * * `description` - The message description. It needs to be unique for each message.
  */
-void pactffi_message_expects_to_receive(struct MessageHandle message, const char *description);
+void pactffi_message_expects_to_receive(MessageHandle message, const char *description);
 
 /**
  * Adds a provider state to the Interaction.
  *
  * * `description` - The provider state description. It needs to be unique for each message
  */
-void pactffi_message_given(struct MessageHandle message, const char *description);
+void pactffi_message_given(MessageHandle message, const char *description);
 
 /**
  * Adds a provider state to the Message with a parameter key and value.
@@ -1428,7 +1761,7 @@ void pactffi_message_given(struct MessageHandle message, const char *description
  * * `name` - Parameter name.
  * * `value` - Parameter value.
  */
-void pactffi_message_given_with_param(struct MessageHandle message,
+void pactffi_message_given_with_param(MessageHandle message,
                                       const char *description,
                                       const char *name,
                                       const char *value);
@@ -1447,7 +1780,7 @@ void pactffi_message_given_with_param(struct MessageHandle message,
  * * `content_type` - Expected content type (e.g. application/json, application/octet-stream)
  * * `size` - number of bytes in the message body to read. This is not required for text bodies (JSON, XML, etc.).
  */
-void pactffi_message_with_contents(struct MessageHandle message,
+void pactffi_message_with_contents(MessageHandle message_handle,
                                    const char *content_type,
                                    const uint8_t *body,
                                    size_t size);
@@ -1458,7 +1791,7 @@ void pactffi_message_with_contents(struct MessageHandle message,
  * * `key` - metadata key
  * * `value` - metadata value.
  */
-void pactffi_message_with_metadata(struct MessageHandle message,
+void pactffi_message_with_metadata(MessageHandle message_handle,
                                    const char *key,
                                    const char *value);
 
@@ -1468,7 +1801,7 @@ void pactffi_message_with_metadata(struct MessageHandle message,
  * Reification is the process of stripping away any matchers, and returning the original contents.
  * NOTE: the returned string needs to be deallocated with the `free_string` function
  */
-const char *pactffi_message_reify(struct MessageHandle message);
+const char *pactffi_message_reify(MessageHandle message_handle);
 
 /**
  * External interface to write out the message pact file. This function should
@@ -1490,7 +1823,7 @@ const char *pactffi_message_reify(struct MessageHandle message);
  * | 1 | The pact file was not able to be written |
  * | 2 | The message pact for the given handle was not found |
  */
-int32_t pactffi_write_message_pact_file(struct MessagePactHandle pact,
+int32_t pactffi_write_message_pact_file(MessagePactHandle pact,
                                         const char *directory,
                                         bool overwrite);
 
@@ -1502,11 +1835,71 @@ int32_t pactffi_write_message_pact_file(struct MessagePactHandle pact,
  * * `name` - the key to set
  * * `value` - the value to set
  */
-void pactffi_with_message_pact_metadata(struct MessagePactHandle pact,
+void pactffi_with_message_pact_metadata(MessagePactHandle pact,
                                         const char *namespace_,
                                         const char *name,
                                         const char *value);
 
+/**
+ * External interface to write out the pact file. This function should
+ * be called if all the consumer tests have passed. The directory to write the file to is passed
+ * as the second parameter. If a NULL pointer is passed, the current working directory is used.
+ *
+ * If overwrite is true, the file will be overwritten with the contents of the current pact.
+ * Otherwise, it will be merged with any existing pact file.
+ *
+ * Returns 0 if the pact file was successfully written. Returns a positive code if the file can
+ * not be written or the function panics.
+ *
+ * # Safety
+ *
+ * The directory parameter must either be NULL or point to a valid NULL terminated string.
+ *
+ * # Errors
+ *
+ * Errors are returned as positive values.
+ *
+ * | Error | Description |
+ * |-------|-------------|
+ * | 1 | The function panicked. |
+ * | 2 | The pact file was not able to be written. |
+ * | 3 | The pact for the given handle was not found. |
+ */
+int32_t pactffi_pact_handle_write_file(PactHandle pact, const char *directory, bool overwrite);
+
+/**
+ * Creates a new V4 asynchronous message and returns a handle to it.
+ *
+ * * `description` - The message description. It needs to be unique for each Message.
+ *
+ * Returns a new `MessageHandle`.
+ */
+MessageHandle pactffi_new_async_message(PactHandle pact, const char *description);
+
+/**
+ * Delete a Pact handle and free the resources used by it.
+ *
+ * # Error Handling
+ *
+ * On failure, this function will return a positive integer value.
+ *
+ * * `1` - The handle is not valid or does not refer to a valid Pact. Could be that it was previously deleted.
+ *
+ */
+unsigned int pactffi_free_pact_handle(PactHandle pact);
+
+/**
+ * Delete a Pact handle and free the resources used by it.
+ *
+ * # Error Handling
+ *
+ * On failure, this function will return a positive integer value.
+ *
+ * * `1` - The handle is not valid or does not refer to a valid Pact. Could be that it was previously deleted.
+ *
+ */
+unsigned int pactffi_free_message_pact_handle(MessagePactHandle pact);
+
 /**
  * External interface to verifier a provider
  *
@@ -1531,7 +1924,10 @@ int32_t pactffi_verify(const char *args);
 
 /**
  * Get a Handle to a newly created verifier. You should call `pactffi_verifier_shutdown` when
- * done with the verifier to free all allocated resources
+ * done with the verifier to free all allocated resources.
+ *
+ * This function is deprecated. Use `pactffi_verifier_new_for_application` which allows the
+ * calling application/framework name and version to be specified.
  *
  * # Safety
  *
@@ -1543,6 +1939,20 @@ int32_t pactffi_verify(const char *args);
  */
 struct VerifierHandle *pactffi_verifier_new(void);
 
+/**
+ * Get a Handle to a newly created verifier. You should call `pactffi_verifier_shutdown` when
+ * done with the verifier to free all allocated resources
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * # Error Handling
+ *
+ * Returns NULL on error.
+ */
+struct VerifierHandle *pactffi_verifier_new_for_application(const char *name, const char *version);
+
 /**
  * Shutdown the verifier and release all resources
  */
@@ -1565,6 +1975,24 @@ void pactffi_verifier_set_provider_info(struct VerifierHandle *handle,
                                         unsigned short port,
                                         const char *path);
 
+/**
+ * Set the filters for the Pact verifier.
+ *
+ * If `filter_description` is not empty, it needs to be as a regular expression.
+ *
+ * `filter_no_state` is a boolean value. Set it to greater than zero to turn the option on.
+ *
+ * # Safety
+ *
+ * All string fields must contain valid UTF-8. Invalid UTF-8
+ * will be replaced with U+FFFD REPLACEMENT CHARACTER.
+ *
+ */
+void pactffi_verifier_set_filter_info(struct VerifierHandle *handle,
+                                      const char *filter_description,
+                                      const char *filter_state,
+                                      unsigned char filter_no_state);
+
 /**
  * Set the provider state for the Pact verifier.
  *
@@ -1583,9 +2011,8 @@ void pactffi_verifier_set_provider_state(struct VerifierHandle *handle,
                                          unsigned char body);
 
 /**
- * Set the verification options for the Pact verifier.
+ * Set the options used by the verifier when calling the provider
  *
- * `publish` is a boolean value. Set it to greater than zero to turn the option on.
  * `disable_ssl_verification` is a boolean value. Set it to greater than zero to turn the option on.
  *
  * # Safety
@@ -1595,13 +2022,33 @@ void pactffi_verifier_set_provider_state(struct VerifierHandle *handle,
  *
  */
 int pactffi_verifier_set_verification_options(struct VerifierHandle *handle,
-                                              unsigned char publish,
-                                              const char *provider_version,
-                                              const char *build_url,
                                               unsigned char disable_ssl_verification,
-                                              unsigned long request_timeout,
-                                              const char *const *provider_tags,
-                                              unsigned short provider_tags_len);
+                                              unsigned long request_timeout);
+
+/**
+ * Set the options used when publishing verification results to the Pact Broker
+ *
+ * # Args
+ *
+ * - `handle` - The pact verifier handle to update
+ * - `provider_version` - Version of the provider to publish
+ * - `build_url` - URL to the build which ran the verification
+ * - `provider_tags` - Collection of tags for the provider
+ * - `provider_tags_len` - Number of provider tags supplied
+ * - `provider_branch` - Name of the branch used for verification
+ *
+ * # Safety
+ *
+ * All string fields must contain valid UTF-8. Invalid UTF-8
+ * will be replaced with U+FFFD REPLACEMENT CHARACTER.
+ *
+ */
+int pactffi_verifier_set_publish_options(struct VerifierHandle *handle,
+                                         const char *provider_version,
+                                         const char *build_url,
+                                         const char *const *provider_tags,
+                                         unsigned short provider_tags_len,
+                                         const char *provider_branch);
 
 /**
  * Set the consumer filters for the Pact verifier.
@@ -1616,6 +2063,18 @@ void pactffi_verifier_set_consumer_filters(struct VerifierHandle *handle,
                                            const char *const *consumer_filters,
                                            unsigned short consumer_filters_len);
 
+/**
+ * Adds a custom header to be added to the requests made to the provider.
+ *
+ * # Safety
+ *
+ * The header name and value must point to a valid NULL terminated string and must contain
+ * valid UTF-8.
+ */
+void pactffi_verifier_add_custom_header(struct VerifierHandle *handle,
+                                        const char *header_name,
+                                        const char *header_value);
+
 /**
  * Adds a Pact file as a source to verify.
  *
@@ -1672,7 +2131,6 @@ void pactffi_verifier_url_source(struct VerifierHandle *handle,
  */
 void pactffi_verifier_broker_source(struct VerifierHandle *handle,
                                     const char *url,
-                                    const char *provider_name,
                                     const char *username,
                                     const char *password,
                                     const char *token);
@@ -1700,14 +2158,18 @@ void pactffi_verifier_broker_source(struct VerifierHandle *handle,
  */
 void pactffi_verifier_broker_source_with_selectors(struct VerifierHandle *handle,
                                                    const char *url,
-                                                   const char *provider_name,
                                                    const char *username,
                                                    const char *password,
                                                    const char *token,
                                                    unsigned char enable_pending,
                                                    const char *include_wip_pacts_since,
                                                    const char *const *provider_tags,
-                                                   unsigned short provider_tags_len);
+                                                   unsigned short provider_tags_len,
+                                                   const char *provider_branch,
+                                                   const char *const *consumer_version_selectors,
+                                                   unsigned short consumer_version_selectors_len,
+                                                   const char *const *consumer_version_tags,
+                                                   unsigned short consumer_version_tags_len);
 
 /**
  * Runs the verification.
@@ -1787,4 +2249,90 @@ const char *pactffi_verifier_logs(const struct VerifierHandle *handle);
  */
 const char *pactffi_verifier_logs_for_provider(const char *provider_name);
 
+/**
+ * Extracts the standard output for the verification run. The returned string will need to be
+ * freed with the `free_string` function call to avoid leaking memory.
+ *
+ * * `strip_ansi` - This parameter controls ANSI escape codes. Setting it to a non-zero value
+ * will cause the ANSI control codes to be stripped from the output.
+ *
+ * Will return a NULL pointer if the handle is invalid.
+ */
+const char *pactffi_verifier_output(const struct VerifierHandle *handle, unsigned char strip_ansi);
+
+/**
+ * Extracts the verification result as a JSON document. The returned string will need to be
+ * freed with the `free_string` function call to avoid leaking memory.
+ *
+ * Will return a NULL pointer if the handle is invalid.
+ */
+const char *pactffi_verifier_json(const struct VerifierHandle *handle);
+
+/**
+ * Add a plugin to be used by the test. The plugin needs to be installed correctly for this
+ * function to work.
+ *
+ * * `plugin_name` is the name of the plugin to load.
+ * * `plugin_version` is the version of the plugin to load. It is optional, and can be NULL.
+ *
+ * Returns zero on success, and a positive integer value on failure.
+ *
+ * Note that plugins run as separate processes, so will need to be cleaned up afterwards by
+ * calling `pactffi_cleanup_plugins` otherwise you have plugin processes left running.
+ *
+ * # Safety
+ *
+ * `plugin_name` must be a valid pointer to a NULL terminated string. `plugin_version` may be null,
+ * and if not NULL must also be a valid pointer to a NULL terminated string.
+ *
+ * # Errors
+ *
+ * * `1` - A general panic was caught.
+ * * `2` - Failed to load the plugin.
+ * * `3` - Pact Handle is not valid.
+ *
+ * When an error errors, LAST_ERROR will contain the error message.
+ */
+unsigned int pactffi_using_plugin(PactHandle pact,
+                                  const char *plugin_name,
+                                  const char *plugin_version);
+
+/**
+ * Decrement the access count on any plugins that are loaded for the Pact. This will shutdown
+ * any plugins that are no longer required (access count is zero).
+ */
+void pactffi_cleanup_plugins(PactHandle pact);
+
+/**
+ * Setup the interaction part using a plugin. The contents is a JSON string that will be passed on to
+ * the plugin to configure the interaction part. Refer to the plugin documentation on the format
+ * of the JSON contents.
+ *
+ * Returns zero on success, and a positive integer value on failure.
+ *
+ * * `interaction` - Handle to the interaction to configure.
+ * * `part` - The part of the interaction to configure (request or response). It is ignored for messages.
+ * * `content_type` - NULL terminated C string of the content type of the part.
+ * * `contents` - NULL terminated C string of the JSON contents that gets passed to the plugin.
+ *
+ * # Safety
+ *
+ * `content_type` and `contents` must be a valid pointers to NULL terminated strings.
+ *
+ * # Errors
+ *
+ * * `1` - A general panic was caught.
+ * * `2` - The mock server has already been started.
+ * * `3` - The interaction handle is invalid.
+ * * `4` - The content type is not valid.
+ * * `5` - The contents JSON is not valid JSON.
+ * * `6` - The plugin returned an error.
+ *
+ * When an error errors, LAST_ERROR will contain the error message.
+ */
+unsigned int pactffi_interaction_contents(InteractionHandle interaction,
+                                          enum InteractionPart part,
+                                          const char *content_type,
+                                          const char *contents);
+
 #endif /* pact_ffi_h */