Commit 6374226d authored by Matthias Clasen's avatar Matthias Clasen
Browse files

Add documentation for content (de)serializers

parent e9179493
......@@ -30,11 +30,11 @@
/**
* SECTION:gdkcontentdeserializer
* @Short_description: Deserialize content for transfer
* @Title: GdkContentSerializer
* @See_also: #GdkContentDeserializer
* @Title: GdkContentDeserializer
* @See_also: #GdkContentSerializer
*
* A GdkContentDeserializer is used to deserialize content for inter-application
* data transfers.
* A GdkContentDeserializer is used to deserialize content received via
* inter-application data transfers.
*/
typedef struct _Deserializer Deserializer;
......@@ -366,6 +366,17 @@ gdk_content_deserializer_return_error (GdkContentDeserializer *deserializer,
gdk_content_deserializer_return_success (deserializer);
}
/**
* gdk_content_register_deserializer:
* @mime_type: the mime type which the function can deserialize from
* @type: the type of objects that the function creates
* @deserialize: the callback
* @data: data that @deserialize can access
* @notify: destroy notify for @data
*
* Registers a function to create objects of a given @type from
* a serialized representation with the given mime type.
*/
void
gdk_content_register_deserializer (const char *mime_type,
GType type,
......@@ -415,6 +426,15 @@ lookup_deserializer (const char *mime_type,
return NULL;
}
/**
* gdk_content_formats_union_deserialize_gtypes:
* @formats: a #GdkContentFormats
*
* Add GTypes for mime types in @formats for which deserializers are
* registered.
*
* Return: a new #GdkContentFormats
*/
GdkContentFormats *
gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)
{
......@@ -441,6 +461,15 @@ gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)
return gdk_content_formats_builder_free (builder);
}
/**
* gdk_content_formats_union_deserialize_mime_types:
* @formats: a #GdkContentFormats
*
* Add mime types for GTypes in @formats for which deserializers are
* registered.
*
* Return: a new #GdkContentFormats
*/
GdkContentFormats *
gdk_content_formats_union_deserialize_mime_types (GdkContentFormats *formats)
{
......@@ -478,6 +507,20 @@ deserialize_not_found (GdkContentDeserializer *deserializer)
gdk_content_deserializer_return_error (deserializer, error);
}
/**
* gdk_content_deserialize_async:
* @stream: a #GInputStream to read the serialized content from
* @mime_type: the mime type to deserialize from
* @type: the GType to deserialize from
* @io_priority: the io priority of the operation
* @cancellable: (nullable): optional #GCancellable object
* @callback: (scope async): callback to call when the operation is done
* @user_data: (closure): data to pass to the callback function
*
* Read content from the given input stream and deserialize it, asynchronously.
* When the operation is finished, @callback will be called. You can then
* call gdk_content_deserialize_finish() to get the result of the operation.
*/
void
gdk_content_deserialize_async (GInputStream *stream,
const char *mime_type,
......@@ -506,6 +549,17 @@ gdk_content_deserialize_async (GInputStream *stream,
user_data);
}
/**
* gdk_content_deserialize_finish:
* @result: the #GAsyncResult
* @value: return location for the result of the operation
* @error: return location for an error
*
* Finishes a content deserialization operation.
*
* Returns: %TRUE if the operation was successful. In this case, @value is set.
* %FALSE if an error occurred. In this case, @error is set
*/
gboolean
gdk_content_deserialize_finish (GAsyncResult *result,
GValue *value,
......
......@@ -32,8 +32,22 @@ G_BEGIN_DECLS
#define GDK_CONTENT_DESERIALIZER(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_DESERIALIZER, GdkContentDeserializer))
#define GDK_IS_CONTENT_DESERIALIZER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_DESERIALIZER))
/**
* GdkContentDeserializer:
*
* Should not be accessed directly.
*/
typedef struct _GdkContentDeserializer GdkContentDeserializer;
/**
* GdkContentDeserializeFunc:
* @deserializer: a #GdkContentDeserializer
*
* The type of a function that can be registered with gdk_content_register_deserializer().
* When the function gets called to operate on content, it can call functions on the
* @deserializer object to obtain the mime type, input stream, user data, etc. for its
* operation.
*/
typedef void (* GdkContentDeserializeFunc) (GdkContentDeserializer *deserializer);
GDK_AVAILABLE_IN_3_94
......
......@@ -39,6 +39,12 @@
* data transfers.
*/
/**
* GdkContentSerializer:
*
* Contains only private fields and should not be directly accessed.
*/
typedef struct _Serializer Serializer;
struct _Serializer
......@@ -369,6 +375,17 @@ gdk_content_serializer_return_error (GdkContentSerializer *serializer,
gdk_content_serializer_return_success (serializer);
}
/**
* gdk_content_register_serializer:
* @type: the type of objects that the function can serialize
* @mime_type: the mime type to serialize to
* @serialize: the callback
* @data: data that @serialize can access
* @notify: destroy notify for @data
*
* Registers a function to convert objects of the given @type to
* a serialized representation with the given mime type.
*/
void
gdk_content_register_serializer (GType type,
const char *mime_type,
......@@ -418,6 +435,15 @@ lookup_serializer (const char *mime_type,
return NULL;
}
/**
* gdk_content_formats_union_serialize_gtypes:
* @formats: a #GdkContentFormats
*
* Add GTypes for the mime types in @formats for which serializers are
* registered.
*
* Return: a new #GdkContentFormats
*/
GdkContentFormats *
gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)
{
......@@ -444,6 +470,15 @@ gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)
return gdk_content_formats_builder_free (builder);
}
/**
* gdk_content_formats_union_serialize_mime_types:
* @formats: a #GdkContentFormats
*
* Add mime types for GTypes in @formats for which serializers are
* registered.
*
* Return: a new #GdkContentFormats
*/
GdkContentFormats *
gdk_content_formats_union_serialize_mime_types (GdkContentFormats *formats)
{
......@@ -481,6 +516,20 @@ serialize_not_found (GdkContentSerializer *serializer)
gdk_content_serializer_return_error (serializer, error);
}
/**
* gdk_content_serialize_async:
* @stream: a #GOutputStream to write the serialized content to
* @mime_type: the mime type to serialize to
* @value: the content to serialize
* @io_priority: the io priority of the operation
* @cancellable: (nullable): optional #GCancellable object
* @callback: (scope async): callback to call when the operation is done
* @user_data: (closure): data to pass to the callback function
*
* Serialize content and write it to the given output stream, asynchronously.
* When the operation is finished, @callback will be called. You can then
* call gdk_content_serialize_finish() to get the result of the operation.
*/
void
gdk_content_serialize_async (GOutputStream *stream,
const char *mime_type,
......@@ -509,6 +558,16 @@ gdk_content_serialize_async (GOutputStream *stream,
user_data);
}
/**
* gdk_content_serialize_finish:
* @result: the #GAsyncResult
* @error: return location for an error
*
* Finishes a content serialization operation.
*
* Returns: %TRUE if the operation was successful, %FALSE if an
* error occurred. In this case, @error is set
*/
gboolean
gdk_content_serialize_finish (GAsyncResult *result,
GError **error)
......
......@@ -32,8 +32,22 @@ G_BEGIN_DECLS
#define GDK_CONTENT_SERIALIZER(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_SERIALIZER, GdkContentSerializer))
#define GDK_IS_CONTENT_SERIALIZER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_SERIALIZER))
/**
* GdkContentSerializer:
*
* Should not be accessed directly.
*/
typedef struct _GdkContentSerializer GdkContentSerializer;
/**
* GdkContentSerializeFunc:
* @serializer: a #GdkContentSerializer
*
* The type of a function that can be registered with gdk_content_register_serializer().
* When the function gets called to operate on content, it can call functions on the
* @serializer object to obtain the mime type, output stream, user data, etc. for its
* operation.
*/
typedef void (* GdkContentSerializeFunc) (GdkContentSerializer *serializer);
GDK_AVAILABLE_IN_3_94
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment