MidgardBlob

MidgardBlob — Files and binary data.

Synopsis

#include <midgard/midgard.h>

                    MidgardBlob;
struct              MidgardBlobClass;
MidgardBlob *       midgard_blob_new                    (MidgardObject *attachment,
                                                         const gchar *encoding);
MidgardBlob *       midgard_blob_create_blob            (MidgardObject *attachment,
                                                         const gchar *encoding);
gchar *             midgard_blob_read_content           (MidgardBlob *self,
                                                         gsize *bytes_read);
gboolean            midgard_blob_write_content          (MidgardBlob *self,
                                                         const gchar *content);
GIOChannel *        midgard_blob_get_handler            (MidgardBlob *self,
                                                         const gchar *mode,
                                                         GError **error);
const gchar *       midgard_blob_get_path               (MidgardBlob *self);
gboolean            midgard_blob_exists                 (MidgardBlob *self);
gboolean            midgard_blob_remove_file            (MidgardBlob *self,
                                                         GError **error);

Object Hierarchy

  GObject
   +----MidgardBlob

Properties

  "attachment"               MidgardObject*        : Read / Write / Construct Only
  "content"                  gchar*                : Read / Write
  "encoding"                 gchar*                : Read / Write / Construct Only
  "parentguid"               gchar*                : Read / Write

Description

MidgardBlob class provides transparent access to real files located in filesystem. It's a proxy between database objects (usually midgard_attachment) and real files like images or documents.

Main MidgardBlob approaches:

  • Binary data doesn't have to be stored together with database record ( MidgardObject ).

  • One object may have unlimited attachments.

  • One blob may be shared among different objects ( of different classes even ).

  • You may attach attachment to another attachment ( notes to documentation or image thumbnails ).

  • Binary file is independent from objects

Details

MidgardBlob

typedef struct _MidgardBlob MidgardBlob;


struct MidgardBlobClass

struct MidgardBlobClass {
	GObjectClass parent;

	gchar *(*read_content) (MidgardBlob *self, gsize *bytes_read);
	gboolean (*write_content) (MidgardBlob *self, const gchar *content);
	gboolean (*remove_file) (MidgardBlob *self, GError **error);
	gboolean (*exists) (MidgardBlob *self);
	const gchar *(*get_path) (MidgardBlob *self);
	GIOChannel *(*get_handler) (MidgardBlob *self, const gchar *mode, GError **error);
};


midgard_blob_new ()

MidgardBlob *       midgard_blob_new                    (MidgardObject *attachment,
                                                         const gchar *encoding);

Default encoding is UTF-8. Set NULL encoding if such is required.

Instatiate new Midgard Blob object for the given midgard_attachment object.

This constructor defines new relative path for attachment, if midgard_attachment is associated with midgard_blob and its location is empty. In any other case, location is not changed.

attachment :

MidgardObject of MIDGARD_TYPE_ATTACHMENT type.

encoding :

file encoding. [allow-none]

Returns :

newly instatiated MidgardBlob object or NULL on failure

midgard_blob_create_blob ()

MidgardBlob *       midgard_blob_create_blob            (MidgardObject *attachment,
                                                         const gchar *encoding);

Invokes midgard_blob_new() and it's designed for language bindings, in whic, that function can not be invoked explicitly.

attachment :

MidgardObject of MIDGARD_TYPE_ATTACHMENT type.

encoding :

file encoding. [allow-none]

Returns :

new MidgardBlob instance. [transfer full]

Since 10.05.1


midgard_blob_read_content ()

gchar *             midgard_blob_read_content           (MidgardBlob *self,
                                                         gsize *bytes_read);

Returned content should be freed when no longer needed. bytes_read holds size of returned content.

This function should be used to get content of small files. For large and huge ones midgard_blob_get_handler should be used to get file handle.

self :

MidgardBlob self instance

bytes_read :

number of bytes read. [out]

Returns :

content of the file, or NULL on failure

midgard_blob_write_content ()

gboolean            midgard_blob_write_content          (MidgardBlob *self,
                                                         const gchar *content);

Write given content to a file.

self :

MidgardBlob self instance.

content :

content which should be written to file.

Returns :

TRUE if content has been written to file, FALSE otherwise.

midgard_blob_get_handler ()

GIOChannel *        midgard_blob_get_handler            (MidgardBlob *self,
                                                         const gchar *mode,
                                                         GError **error);

The main idea is to get file handler. On C level it returns GIOChannel, but language bindings could return typical file handler or anything else which is needed for particular language.

Returned channel is owned by midgard_blob and should not be freed or unreferenced.

self :

MidgardBlob instance

mode :

fopen mode (r, w, a, b). Default is 'w'.

error :

a pointer to store error. [allow-none]

Returns :

GIOChannel or NULL. [transfer none]

midgard_blob_get_path ()

const gchar *       midgard_blob_get_path               (MidgardBlob *self);

Returned path is owned by midgard_blob and should not be freed. It basically contains blobdir and relative file's location.

self :

MidgardBlob instance

Returns :

absolute path or NULL if path is not set yet.

midgard_blob_exists ()

gboolean            midgard_blob_exists                 (MidgardBlob *self);

Check if file associated with midgard_blob exists. This function will also return FALSE, if file is not yet associated.

self :

MidgardBlob instance

Returns :

TRUE if file exists, FALSE otherwise

midgard_blob_remove_file ()

gboolean            midgard_blob_remove_file            (MidgardBlob *self,
                                                         GError **error);

Deletes a file which is associated with blob and located at attachment's location which is initialized for blob. midgard_blob_exists should be invoked if file may be already deleted, for example when one file is shared among many attachments.

self :

MidgardBlob self instance.

Returns :

TRUE on success, FALSE otherwise

Property Details

The "attachment" property

  "attachment"               MidgardObject*        : Read / Write / Construct Only


The "content" property

  "content"                  gchar*                : Read / Write

Default value: ""


The "encoding" property

  "encoding"                 gchar*                : Read / Write / Construct Only

Default value: ""


The "parentguid" property

  "parentguid"               gchar*                : Read / Write

Default value: ""