Address of the local mock server if it's running, or %NULL otherwise. This will be non-%NULL between calls to uhm_server_run() and
uhm_server_stop(). The address is a physical IP address, e.g. 127.0.0.1.
This should not normally need to be passed into client code under test, unless the code references IP addresses specifically. The mock server runs a DNS resolver which automatically redirects client requests for known domain names to this address (#UhmServer:resolver).
%TRUE if network traffic should be logged to a trace file (specified by calling uhm_server_start_trace()). This operates independently of whether traffic is online or being handled locally by the mock server. Use this in conjunction with #UhmServer:enable-online to either log online traffic, or replay logged traffic locally.
%TRUE if network traffic should reach the Internet as normal; %FALSE to redirect it to the local mock server. Use this in conjunction with #UhmServer:enable-logging to either log online traffic, or replay logged traffic locally.
Port of the local mock server if it's running, or 0 otherwise. This will be non-0 between
calls to uhm_server_run() and uhm_server_stop().
It is intended that this port be passed into the client code under test, to substitute for the default HTTPS port (443) which it would otherwise use.
Mock resolver used to redirect HTTP requests from specified domain names to the local mock server instance. This will always be set while the server is running (between calls to uhm_server_run() and uhm_server_stop()), and is %NULL otherwise.
Use the resolver specified in this property to add domain names which are expected to be requested by the current trace. Domain names not added to the resolver will be rejected by the mock server. The set of domain names in the resolver will be reset when uhm_server_stop() is called.
TLS certificate for the mock server to use when serving HTTPS pages. If this is non-%NULL, the server will always use HTTPS. If it is %NULL, the server will always use HTTP. The TLS certificate may be changed after constructing the #UhmServer, but changes to the property will not take effect until the next call to uhm_server_run().
A certificate and private key may be generated by executing:
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -nodes. These files may then be used to construct a
#GTlsCertificate by calling g_tls_certificate_new_from_files().
Alternatively, a default #GTlsCertificate which wraps a dummy certificate (not signed by any certificate authority) may be set by calling uhm_server_set_default_tls_certificate(). This may be used as the #UhmServer:tls-certificate if the code under test has no specific requirements of the certificate used by the mock server it's tested against.
Directory relative to which all trace files specified in calls to uhm_server_start_trace() will be resolved. This is not used for any other methods, but must be non-%NULL if uhm_server_start_trace() is called.
Creates a binding between source_property on source and target_property
on target.
Whenever the source_property is changed the target_property is
updated using the same value. For instance:
g_object_bind_property (action, "active", widget, "sensitive", 0);
Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance.
If flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
if target_property on target changes then the source_property on source
will be updated as well.
The binding will automatically be removed when either the source or the
target instances are finalized. To remove the binding without affecting the
source and the target you can just call g_object_unref() on the returned
#GBinding instance.
Removing the binding by calling g_object_unref() on it must only be done if
the binding, source and target are only used from a single thread and it
is clear that both source and target outlive the binding. Especially it
is not safe to rely on this if the binding, source or target can be
finalized from different threads. Keep another reference to the binding and
use g_binding_unbind() instead to be on the safe side.
A #GObject can have multiple bindings.
the property on source to bind
the target #GObject
the property on target to bind
flags to pass to #GBinding
Creates a binding between source_property on source and target_property
on target, allowing you to set the transformation functions to be used by
the binding.
This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers.
the property on source to bind
the target #GObject
the property on target to bind
flags to pass to #GBinding
a #GClosure wrapping the transformation function from the source to the target, or %NULL to use the default
a #GClosure wrapping the transformation function from the target to the source, or %NULL to use the default
Remove a #UhmServer:compare-messages filter function installed previously by calling something like uhm_server_filter_ignore_parameter_values().
It is an error to call this function with an invalid filter_id.
filter ID returned by the filter addition function
Convenience function to finish logging to or reading from a trace file previously passed to uhm_server_start_trace() or uhm_server_start_trace_full().
If #UhmServer:enable-online is %FALSE, this will shut down the mock server (as if uhm_server_stop() had been called).
Install a #UhmServer:compare-messages filter function which will override the
default comparison function to one which ignores differences in the values of
the given query parameter_names. The named parameters must still be present
in the query, however.
The filter will remain in place for the lifetime of the #UhmServer, until
uhm_server_compare_messages_remove_filter() is called with the returned
filter ID.
Note that currently only one of the installed comparison functions will be used. This may change in future.
%NULL-terminated array of parameter names to ignore
This function is intended for #GObject implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().
Increases the freeze count on object. If the freeze count is
non-zero, the emission of "notify" signals on object is
stopped. The signals are queued until the freeze count is decreased
to zero. Duplicate notifications are squashed so that at most one
#GObject::notify signal is emitted for each property modified while the
object is frozen.
This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
Gets the value of the #UhmServer:address property.
Gets a named field from the objects table of associations (see g_object_set_data()).
name of the key for that association
Gets the value of the #UhmServer:enable-logging property.
Gets the value of the #UhmServer:enable-online property.
Gets the value of the #UhmServer:port property.
Gets a property of an object.
The value can be:
In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset().
Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.
the name of the property to get
return location for the property value
This function gets back user data pointers stored via g_object_set_qdata().
A #GQuark, naming the user data pointer
Gets the value of the #UhmServer:tls-certificate property.
Gets n_properties properties for an object.
Obtained properties will be set to values. All properties must be valid.
Warnings will be emitted and undefined behaviour may result if invalid
properties are passed in.
the names of each property to get
the values of each property to get
Checks whether object has a [floating][floating-ref] reference.
Synchronously loads the given trace_file of network messages, ready to simulate a network conversation by matching
requests against the file and returning the associated responses. Call uhm_server_run() to start the mock
server afterwards.
Loading the trace file may be cancelled from another thread using cancellable.
On error, error will be set and the state of the #UhmServer will not change. A #GIOError will be set if there is
a problem reading the trace file.
trace file to load
a #GCancellable, or %NULL
Asynchronous version of uhm_server_load_trace(). In callback, call uhm_server_load_trace_finish() to complete the operation.
trace file to load
a #GCancellable, or %NULL
function to call once the async operation is complete
Finishes an asynchronous operation started by uhm_server_load_trace_async().
On error, error will be set and the state of the #UhmServer will not change.
See uhm_server_load_trace() for details on the error domains used.
asynchronous operation result passed to the callback
Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.
Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.
the name of a property installed on the class of object.
Emits a "notify" signal for the property specified by pspec on object.
This function omits the property name lookup, hence it is faster than g_object_notify().
One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:
enum
{
PROP_0,
PROP_FOO,
PROP_LAST
};
static GParamSpec *properties[PROP_LAST];
static void
my_object_class_init (MyObjectClass *klass)
{
properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
0, 100,
50,
G_PARAM_READWRITE);
g_object_class_install_property (gobject_class,
PROP_FOO,
properties[PROP_FOO]);
}
and then notify a change on the "foo" property with:
g_object_notify_by_pspec (self, properties[PROP_FOO]);
the #GParamSpec of a property installed on the class of object.
Indicates to the mock server that a single new line of a message was received from the real server. The message line may be appended to the current trace file if logging is enabled (#UhmServer:enable-logging is %TRUE), adding a newline character at the end. If logging is disabled but online mode is enabled (#UhmServer:enable-online is %TRUE), the message line will be compared to the next expected line in the existing trace file. Otherwise, this function is a no-op.
On failure, error will be set and the #UhmServer state will remain unchanged apart from the parse state machine, which will remain
in the state reached after parsing message_chunk. A %G_IO_ERROR will be returned if writing to the trace file failed. If in
comparison mode and the received message chunk corresponds to an unexpected message in the trace file, a %UHM_SERVER_ERROR will
be returned.
single line of a message which was received
length of message_chunk in bytes
Convenience version of uhm_server_received_message_chunk() which takes the
message direction and data separately, as provided by libsoup in a
#SoupLoggerPrinter callback.
static void soup_log_printer (SoupLogger *logger, SoupLoggerLogLevel level, char direction, const char data, gpointer user_data) { / Pass the data to libuhttpmock. */ UhmServer *mock_server = UHM_SERVER (user_data); uhm_server_received_message_chunk_with_direction (mock_server, direction, data, strlen (data), NULL); }
mock_server = uhm_server_new (); session = soup_session_new ();
logger = soup_logger_new (SOUP_LOGGER_LOG_BODY, -1); soup_logger_set_printer (logger, (SoupLoggerPrinter) soup_log_printer, g_object_ref (mock_server), g_object_unref); soup_session_add_feature (session, SOUP_SESSION_FEATURE (logger)); g_object_unref (logger);
/* Do something with mock_server here. */
single character indicating the direction of message transmission
single line of a message which was received
length of data in bytes
Increase the reference count of object, and possibly remove the
[floating][floating-ref] reference, if object has a floating reference.
In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.
Since GLib 2.56, the type of object will be propagated to the return type
under the same conditions as for g_object_ref().
Runs the mock server, binding to a loopback TCP/IP interface and preparing a HTTPS server which is ready to accept requests. The TCP/IP address and port number are chosen randomly out of the loopback addresses, and are exposed as #UhmServer:address and #UhmServer:port once this function has returned. A #UhmResolver (exposed as #UhmServer:resolver) is set as the default #GResolver while the server is running.
The server is started in a worker thread, so this function returns immediately and the server continues to run in the background. Use uhm_server_stop() to shut it down.
This function always succeeds.
Releases all references to other objects. This can be used to break reference cycles.
This function should only be called from object system implementations.
Each object carries around a table of associations from strings to pointers. This function lets you set an association.
If the object already had an association with that name, the old association will be destroyed.
Internally, the key is converted to a #GQuark using g_quark_from_string().
This means a copy of key is kept permanently (even after object has been
finalized) — so it is recommended to only use a small, bounded set of values
for key in your program, to avoid the #GQuark storage growing unbounded.
name of the key
data to associate with that key
Sets the value of the #UhmServer:tls-certificate property to the default TLS certificate built in to libuhttpmock. This default certificate is not signed by any certificate authority, and contains minimal metadata details. It may be used by clients which have no special certificate requirements; clients which have special requirements should construct a custom #GTlsCertificate and pass it to uhm_server_set_tls_certificate().
Sets the value of the #UhmServer:enable-logging property.
%TRUE to log client network traffic to a trace file; %FALSE otherwise
Sets the value of the #UhmServer:enable-online property.
%TRUE to not intercept and handle network connections from client code; %FALSE otherwise
Set the domain names which are expected to have requests made of them by the client code interacting with this #UhmServer.
This is a convenience method which calls uhm_resolver_add_A() on the server’s #UhmResolver for each of the domain names
listed in domain_names. It associates them with the server’s current IP address, and automatically updates the mappings
if the IP address or resolver change.
Note that this will reset all records on the server’s #UhmResolver, replacing all of them with the provided domain_names.
It is safe to add further domain names to the #UhmResolver in a callback for the #GObject::notify signal for #UhmServer:resolver;
that signal is emitted after the resolver is cleared and these domain_names are added.
%NULL-terminated array of domain names to expect, or %NULL to not expect any
Sets a property on an object.
the name of the property to set
the value
Sets the value of the #UhmServer:tls-certificate property.
TLS certificate for the server to use; or %NULL to serve HTTP only
Starts a mock server which follows the trace file of filename trace_name in the #UhmServer:trace-directory directory.
See uhm_server_start_trace_full() for further documentation.
This function has undefined behaviour if #UhmServer:trace-directory is %NULL.
On failure, error will be set and the #UhmServer state will remain unchanged. See uhm_server_start_trace_full() for
details of the error domains used.
name of the trace
Convenience function to start logging to or reading from the given trace_file, depending on the values of #UhmServer:enable-logging and
#UhmServer:enable-online.
If #UhmServer:enable-logging is %TRUE, a log handler will be set up to redirect all client network activity into the given trace_file.
If trace_file already exists, it will be overwritten.
If #UhmServer:enable-online is %FALSE, the given trace_file is loaded using uhm_server_load_trace() and then a mock server is
started using uhm_server_run().
On failure, error will be set and the #UhmServer state will remain unchanged. A #GIOError will be set if logging is enabled
(#UhmServer:enable-logging) and there is a problem writing to the trace file; or if a trace needs to be loaded and there is a problem
reading from the trace file.
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
name of the key
This function gets back user data pointers stored via
g_object_set_qdata() and removes the data from object
without invoking its destroy() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
void
object_add_to_user_list (GObject *object,
const gchar *new_string)
{
// the quark, naming the object data
GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
// retrieve the old string list
GList *list = g_object_steal_qdata (object, quark_string_list);
// prepend new string
list = g_list_prepend (list, g_strdup (new_string));
// this changed 'list', so we need to set it again
g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
GList *node, *list = data;
for (node = list; node; node = node->next)
g_free (node->data);
g_list_free (list);
}
Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().
A #GQuark, naming the user data pointer
Stops a mock server started by calling uhm_server_run(). This shuts down the server's worker thread and unbinds it from its TCP/IP socket.
This unloads any trace file loaded by calling uhm_server_load_trace() (or its asynchronous counterpart). It also resets the set of domain names loaded into the #UhmServer:resolver.
This function always succeeds.
Reverts the effect of a previous call to
g_object_freeze_notify(). The freeze count is decreased on object
and when it reaches zero, queued "notify" signals are emitted.
Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued.
It is an error to call this function when the freeze count is zero.
Unloads the current trace file of network messages, as loaded by uhm_server_load_trace() or uhm_server_load_trace_async().
Decreases the reference count of object. When its reference count
drops to 0, the object is finalized (i.e. its memory is freed).
If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this.
This function essentially limits the life time of the closure to
the life time of the object. That is, when the object is finalized,
the closure is invalidated by calling g_closure_invalidate() on
it, in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, g_object_ref() and g_object_unref() are
added as marshal guards to the closure, to ensure that an extra
reference count is held on object during invocation of the
closure. Usually, this function will be called on closures that
use this object as closure data.
#GClosure to watch
Find the #GParamSpec with the given name for an
interface. Generally, the interface vtable passed in as g_iface
will be the default vtable from g_type_default_interface_ref(), or,
if you know the interface has already been loaded,
g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
name of a property to look up.
Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created #GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.
This function is meant to be called from the interface's default
vtable initialization function (the class_init member of
#GTypeInfo.) It must not be called after after class_init has
been called for any object types implementing this interface.
If pspec is a floating reference, it will be consumed.
any interface vtable for the interface, or the default vtable for the interface.
the #GParamSpec for the new property
Lists the properties of an interface.Generally, the interface
vtable passed in as g_iface will be the default vtable from
g_type_default_interface_ref(), or, if you know the interface has
already been loaded, g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
Creates a new instance of a #GObject subtype and sets its properties.
Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.
the type id of the #GObject subtype to instantiate
an array of #GParameter
Convenience version of uhm_server_received_message_chunk() which can be passed directly to soup_logger_set_printer() to forward all libsoup traffic logging to a #UhmServer. The #UhmServer must be passed to soup_logger_set_printer() as its user data.
mock_server = uhm_server_new (); session = soup_session_new ();
logger = soup_logger_new (SOUP_LOGGER_LOG_BODY, -1); soup_logger_set_printer (logger, uhm_server_received_message_chunk_from_soup, g_object_ref (mock_server), g_object_unref); soup_session_add_feature (session, SOUP_SESSION_FEATURE (logger)); g_object_unref (logger);
/* Do something with mock_server here. */
a #SoupLogger
the detail level of this log message
the transmission direction of the message
message data
user data passed to the #SoupLogger, or %NULL
All the fields in the #UhmServer structure are private and should never be accessed directly.