libpurple/image-store.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
  20  */
  21
  22 #ifndef _PURPLE_IMAGE_STORE_H_
  23 #define _PURPLE_IMAGE_STORE_H_
  24 /**
  25  * SECTION:image-store
  26  * @include:image-store.h
  27  * @section_id: libpurple-image-store
  28  * @short_description: a global, temporary storage for images
  29  * @title: Image store
  30  *
  31  * Image store references #PurpleImage's by a simple integer value.
  32  * It's a convenient way to embed images in HTML-like strings.
  33  *
  34  * Integer ID's are tracked for being valid - when a image is destroyed, it's
  35  * also removed from the store. If the application runs for a very long time and
  36  * all possible id numbers from integer range are utilized, it will use
  37  * previously released numbers.
  38  */
  39
  40 #include "image.h"
  41
  42 /**
  43  * PURPLE_IMAGE_STORE_PROTOCOL:
  44  *
  45  * A global URI prefix for images stored in this subsystem.
  46  */
  47 #define PURPLE_IMAGE_STORE_PROTOCOL "purple-image:"
  48
  49 /**
  50  * PURPLE_IMAGE_STORE_STOCK_PROTOCOL:
  51  *
  52  * A global URI prefix for stock images, with names defined by libpurple and
  53  * contents defined by the UI.
  54  */
  55 #define PURPLE_IMAGE_STORE_STOCK_PROTOCOL "purple-stock-image:"
  56
  57 G_BEGIN_DECLS
  58
  59 /**
  60  * purple_image_store_add:
  61  * @image: the image.
  62  *
  63  * Permanently adds an image to the store. If the @image is already in the
  64  * store, it will return its current id.
  65  *
  66  * This function increases @image's reference count, so it won't be destroyed
  67  * until image store subsystem is shut down. Don't decrease @image's reference
  68  * count by yourself - if you don't want the store to hold the reference,
  69  * use #purple_image_store_add_weak.
  70  *
  71  * Returns: the unique identifier for the @image.
  72  */
  73 guint
  74 purple_image_store_add(PurpleImage *image);
  75
  76 /**
  77  * purple_image_store_add_weak:
  78  * @image: the image.
  79  *
  80  * Adds an image to the store without increasing reference count. It will be
  81  * removed from the store when @image gets destroyed.
  82  *
  83  * If the @image is already in the store, it will return its current id.
  84  *
  85  * Returns: the unique identifier for the @image.
  86  */
  87 guint
  88 purple_image_store_add_weak(PurpleImage *image);
  89
  90 /**
  91  * purple_image_store_add_temporary:
  92  * @image: the image.
  93  *
  94  * Adds an image to the store to be used in a short period of time.
  95  * If the @image is already in the store, it will just return its current id.
  96  *
  97  * Increases reference count for the @image for a time long enough to display
  98  * the @image by the UI. In current implementation it's five seconds, but may be
  99  * changed in the future, so if you need more sophisticated reference
 100  * management, implement it on your own.
 101  *
 102  * Returns: the unique identifier for the @image.
 103  */
 104 guint
 105 purple_image_store_add_temporary(PurpleImage *image);
 106
 107 /**
 108  * purple_image_store_get:
 109  * @id: the unique identifier of an image.
 110  *
 111  * Finds the image with a certain identifier within a store.
 112  *
 113  * Returns: (transfer none): the image referenced by @id, or %NULL if it
 114  *          doesn't exists.
 115  */
 116 PurpleImage *
 117 purple_image_store_get(guint id);
 118
 119 /**
 120  * purple_image_store_get_from_uri:
 121  * @uri: the URI of a potential #PurpleImage. Should not be %NULL.
 122  *
 123  * Checks, if the @uri is pointing to any #PurpleImage by referring
 124  * to #PURPLE_IMAGE_STORE_PROTOCOL and returns the image, if it's valid.
 125  *
 126  * The function doesn't throw any warning, if the @uri is for any
 127  * other protocol.
 128  *
 129  * Returns: (transfer none): the image referenced by @uri, or %NULL if it
 130  *          doesn't point to any valid image.
 131  */
 132 PurpleImage *
 133 purple_image_store_get_from_uri(const gchar *uri);
 134
 135 /**
 136  * purple_image_store_get_uri:
 137  * @image: the image.
 138  *
 139  * Generates an URI for the @image, to be retrieved using
 140  * #purple_image_store_get_from_uri.
 141  *
 142  * Returns: (transfer full): the URI for the @image. Should be #g_free'd when
 143  * you done using it.
 144  */
 145 gchar *
 146 purple_image_store_get_uri(PurpleImage *image);
 147
 148 /**
 149  * _purple_image_store_init: (skip)
 150  *
 151  * Initializes the image store subsystem.
 152  */
 153 void
 154 _purple_image_store_init(void);
 155
 156 /**
 157  * _purple_image_store_uninit: (skip)
 158  *
 159  * Uninitializes the image store subsystem.
 160  */
 161 void
 162 _purple_image_store_uninit(void);
 163
 164 G_END_DECLS
 165
 166 #endif /* _PURPLE_IMAGE_STORE_H_ */