Changeset 908

Show
Ignore:
Timestamp:
09/08/06 22:55:03
Author:
pvanhoof
Message:

Added samples to the API docs

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/libtinymail/tny-fs-stream.c

    r900 r908  
    1818 */ 
    1919 
    20 /* Original file: camel-stream-fs.c : file system based stream (Camel source code) 
    21  * 
     20/* Original file: camel-stream-fs.c : file system based stream (Camel  
     21 * source code). Note that this implementation is heavily modified and that 
     22 * therefore bugs aren't necessarily caused by the original authors. 
     23 */ 
     24 
     25/* 
    2226 * Authors: Bertrand Guiheneuf <bertrand@helixcode.com> 
    2327 *          Michael Zucchi <notzed@ximian.com> 
    …… 
    167171 * @fd: The file descriptor to write to or read from 
    168172 * 
    169  * Create an adaptor instance between #TnyStream and a file descriptor 
     173 * Create an adaptor instance between #TnyStream and a file descriptor. Note  
     174 * that you must not to close() fd yourself. The destructor will do that for 
     175 * you. 
     176 * 
     177 * Therefore use it with care. It's more or less an exception in the framework. 
     178 * 
     179 * The the instance will on top of close() when destructing, also fsync() the 
     180 * filedescriptor. It does this depending on its mood, the weather and your 
     181 * wives periods using a complex algorithm that abuses your privacy and might 
     182 * kill your cat and dog. 
    170183 * 
    171184 * Return value: a new #TnyStream instance 
    172185 **/ 
    173 TnyFsStream* 
     186TnyStream* 
    174187tny_fs_stream_new (int fd) 
    175188{ 
    …… 
    178191        tny_fs_stream_set_fd (self, fd); 
    179192 
    180         return self; 
     193        return TNY_STREAM (self); 
    181194} 
    182195 
    …… 
    200213 
    201214        if (priv->fd != -1) 
    202                 close (priv->fd); 
    203  
     215        { 
     216                fsync (priv->fd); 
     217                close (priv->fd);             
     218        } 
    204219        priv->fd = -1; 
    205220 
    …… 
    300315} 
    301316 
    302  
    303 /* 
    304  
    305 static off_t 
    306 stream_seek (CamelSeekableStream *stream, off_t offset, CamelStreamSeekPolicy policy) 
    307 { 
    308         CamelStreamFs *stream_fs = CAMEL_STREAM_FS (stream); 
    309         off_t real = 0; 
    310  
    311         switch (policy) { 
    312         case CAMEL_STREAM_SET: 
    313                 real = offset; 
    314                 break; 
    315         case CAMEL_STREAM_CUR: 
    316                 real = stream->position + offset; 
    317                 break; 
    318         case CAMEL_STREAM_END: 
    319                 if (stream->bound_end == CAMEL_STREAM_UNBOUND) { 
    320                         real = lseek(stream_fs->fd, offset, SEEK_END); 
    321                         if (real != -1) { 
    322                                 if (real<stream->bound_start) 
    323                                         real = stream->bound_start; 
    324                                 stream->position = real; 
    325                         } 
    326                         return real; 
    327                 } 
    328                 real = stream->bound_end + offset; 
    329                 break; 
    330         } 
    331  
    332         if (stream->bound_end != CAMEL_STREAM_UNBOUND) 
    333                 real = MIN (real, stream->bound_end); 
    334         real = MAX (real, stream->bound_start); 
    335  
    336         real = lseek(stream_fs->fd, real, SEEK_SET); 
    337         if (real == -1) 
    338                 return -1; 
    339  
    340         if (real != stream->position && ((CamelStream *)stream)->eos) 
    341                 ((CamelStream *)stream)->eos = FALSE; 
    342  
    343         stream->position = real; 
    344  
    345         return real; 
    346 } 
    347 */ 

  • trunk/libtinymail/tny-fs-stream.h

    r903 r908  
    5555 
    5656GType  tny_fs_stream_get_type (void); 
    57 TnyFsStream* tny_fs_stream_new (int fd); 
     57TnyStream* tny_fs_stream_new (int fd); 
    5858void tny_fs_stream_set_fd (TnyFsStream *self, int fd); 
    5959 

  • trunk/libtinymail/tny-iterator.c

    r906 r908  
    130130 * { 
    131131 *    GObject *cur = tny_iterator_get_current (iter); 
     132 *    ... 
    132133 *    g_object_unref (cur); 
    133134 *    tny_iterator_next (iter); 

  • trunk/libtinymail/tny-list.c

    r900 r908  
    8787 * @item: the item to remove 
    8888 * 
    89  * Removes an item from a list 
    90  * 
    91  * Removing a item might invalidate all existing iterators or put them in an 
    92  * unknown and unspecified state. You'll need to recreate the iterator(s) if you 
    93  * remove an item to be certain. 
    94  * 
    95  * There's no guarantee whatsoever that existing iterators of 'self' will be 
     89 * Removes an item from a list.  Removing a item might invalidate all existing 
     90 * iterators or put them in an unknown and unspecified state. You'll need to  
     91 * recreate the iterator(s) if you remove an item to be certain. 
     92 * 
     93 * If you want to clear a list, consider using the tny_list_foreach or simply 
     94 * destroy the list instance and construct a new one. 
     95 * 
     96 * There's no guarantee whatsoever that existing iterators of @self will be 
    9697 * valid after this method returned. 
    9798 * 
    …… 
    117118 * An iterator is a position indicator for a list. It keeps the position 
    118119 * state of a list iteration. The list itself does not keep any position  
    119  * information. This makes it possible to have multiple list-iterations by 
    120  * consuming multiple iterator instances simultanously. 
     120 * information. Consuming multiple iterator instances makes it possible to 
     121 * have multiple list iterations simultanously (i.e. multiple threads or in 
     122 * in a loop that simultanously works with multiple position states in a 
     123 * single list). 
     124 * 
     125 * Example: 
     126 * <informalexample><programlisting> 
     127 * TnyList *list = tny_simple_list_new (); 
     128 * TnyIterator *iter1 = tny_list_create_iterator (list); 
     129 * TnyIterator *iter2 = tny_list_create_iterator (list); 
     130 * while (!tny_iterator_is_done (iter1)) 
     131 * { 
     132 *      while (!tny_iterator_is_done (iter2)) 
     133 *              tny_iterator_next (iter2); 
     134 *      tny_iterator_next (iter1); 
     135 * } 
     136 * g_object_unref (G_OBJECT (iter1)); 
     137 * g_object_unref (G_OBJECT (iter2)); 
     138 * g_object_unref (G_OBJECT (list)); 
     139 * </programlisting></informalexample> 
    121140 * 
    122141 * The reason why the method isn't called get_iterator is because it's a 
    …… 
    147166 * Calls a function for each element of a #TnyList. It will use an internal 
    148167 * iteration which you don't have to worry about.  
     168 * 
     169 * <informalexample><programlisting> 
     170 * static void 
     171 * list_foreach_item (TnyHeader *header, gpointer user_data) 
     172 * { 
     173 *      g_print ("%s\n", tny_header_get_subject (header)); 
     174 * } 
     175 * </programlisting></informalexample> 
     176 * 
     177 * <informalexample><programlisting> 
     178 * TnyFolder *folder = ... 
     179 * TnyList *headers = tny_simple_list_new (); 
     180 * tny_folder_get_headers (folder, headers, FALSE); 
     181 * tny_list_foreach (headers, list_foreach_item, NULL); 
     182 * g_object_unref (G_OBJECT (list)); 
     183 * </programlisting></informalexample> 
    149184 * 
    150185 * The purpose of this method is to have a fast foreach iteration. Using this 
    …… 
    228263                type = g_type_register_static (G_TYPE_INTERFACE,  
    229264                        "TnyList", &info, 0); 
    230  
    231                 /* g_type_interface_add_prerequisite (type, G_TYPE_OBJECT); */ 
    232265        } 
    233266 

  • trunk/libtinymail/tny-mime-part.c

    r900 r908  
    2828 * Figures out whether or not a mime part is an attachment. An attachment 
    2929 * is typically something with a original filename. Examples are attached 
    30  * files. Examples are not PGP signatures. 
    31  *  
     30 * files. Examples that will return FALSE are PGP signatures. 
     31 * 
     32 * Example: 
     33 * <informalexample><programlisting> 
     34 * TnyMsg *message = ... 
     35 * TnyList *parts = tny_simple_list_new (); 
     36 * tny_msg_get_parts (message, parts); 
     37 * iter = tny_list_create_iterator (parts); 
     38 * while (!tny_iterator_is_done (iter)) 
     39 * { 
     40 *      TnyMimePart *part = TNY_MIME_PART (tny_iterator_get_current (iter)); 
     41 *      if (tny_mime_part_is_attachment (part)) 
     42 *      { 
     43 *              g_print ("Found an attachment (%s)\n", 
     44 *                      tny_mime_part_get_filename (part)); 
     45 *      } 
     46 *      g_object_unref (G_OBJECT (part)); 
     47 *      tny_iterator_next (iter); 
     48 * } 
     49 * g_object_unref (G_OBJECT (iter)); 
     50 * g_object_unref (G_OBJECT (parts)); 
     51 * </programlisting></informalexample> 
     52 * 
    3253 * Return value: whether or not the mime part is an attachment 
    3354 * 
    …… 
    237258 * mime part. Mime parts are encoded before appending it to a message. 
    238259 *  
     260 * Example: 
     261 * <informalexample><programlisting> 
     262 * int fd = open ("/tmp/attachment.png.base64enc", O_WRONLY|O_CREAT, S_IRUSR|S_IWUSR); 
     263 * TnyMimePart *part = ... 
     264 * if (fd != -1) 
     265 * { 
     266 *      TnyFsStream *stream = tny_fs_stream_new (fd); 
     267 *      tny_mime_part_write_to_stream (part, TNY_STREAM (stream)); 
     268 *      g_object_unref (G_OBJECT (stream)); 
     269 * } 
     270 * </programlisting></informalexample> 
    239271 **/ 
    240272void 
    …… 
    260292 * already writing it to the stream efficiently. 
    261293 * 
     294 * Example: 
     295 * <informalexample><programlisting> 
     296 * int fd = open ("/tmp/attachment.png", O_WRONLY|O_CREAT, S_IRUSR|S_IWUSR); 
     297 * TnyMimePart *part = ... 
     298 * if (fd != -1) 
     299 * { 
     300 *      TnyFsStream *stream = tny_fs_stream_new (fd); 
     301 *      tny_mime_part_decode_to_stream (part, TNY_STREAM (stream)); 
     302 *      g_object_unref (G_OBJECT (stream)); 
     303 * } 
     304 * </programlisting></informalexample> 
     305 * 
    262306 **/ 
    263307void 
    …… 
    280324 * Set the stream from which the message part will read its content 
    281325 * 
     326 * Example: 
     327 * <informalexample><programlisting> 
     328 * int fd = open ("/tmp/attachment.png", ...); 
     329 * TnyMimePart *part = ... 
     330 * if (fd != -1) 
     331 * { 
     332 *      TnyFsStream *stream = tny_fs_stream_new (fd); 
     333 *      tny_mime_part_construct_from_stream (part, TNY_STREAM (stream)); 
     334 * } 
     335 * </programlisting></informalexample> 
     336 * 
    282337 * Return value: 0 on success or -1 on failure 
    283338 **/ 
    …… 
    318373 * @self: a #TnyMimePart object 
    319374 *  
    320  * A read-only string in the format "type/subtype". You shouldn't free the  
     375 * A read-only string in the format "type/subtype". You shouldn't free the  
    321376 * returned value. 
    322377 * 
    323378 * Return value: content-type of a message part as a read-only string 
    324  * 
    325379 **/ 
    326380const gchar* 
    …… 
    340394 * @content_type: The content type in the string format type/subtype 
    341395 *  
    342  * Efficiently checks whether a part is of type content_type 
     396 * Efficiently checks whether a part is of type content_type. You can use things 
     397 * like "type/*" for matching. Only * works, stands for 'any', and it's not  
     398 * (like) a regular expression. 
     399 * 
     400 * Example: 
     401 * <informalexample><programlisting> 
     402 * TnyMsg *message = ... 
     403 * TnyList *parts = tny_simple_list_new (); 
     404 * tny_msg_get_parts (message, parts); 
     405 * iter = tny_list_create_iterator (parts); 
     406 * while (!tny_iterator_is_done (iter)) 
     407 * { 
     408 *      TnyMimePart *part = TNY_MIME_PART (tny_iterator_get_current (iter)); 
     409 *      if (tny_mime_part_content_type_is (part, "text/*")) 
     410 *              g_print ("Found an E-mail body\n"); 
     411 *      if (tny_mime_part_content_type_is (part, "text/html")) 
     412 *              g_print ("Found an E-mail HTML body\n");  
     413 *      g_object_unref (G_OBJECT (part)); 
     414 *      tny_iterator_next (iter); 
     415 * } 
     416 * g_object_unref (G_OBJECT (iter)); 
     417 * g_object_unref (G_OBJECT (parts)); 
     418 * </programlisting></informalexample> 
    343419 * 
    344420 * Return value: Whether or not the part is the content type 

  • trunk/libtinymail/tny-msg.c

    r900 r908  
    5050 *  
    5151 * Get a read-only list of mime-parts of this message. 
     52 * 
     53 * Example: 
     54 * <informalexample><programlisting> 
     55 * TnyMsg *message = ... 
     56 * TnyList *parts = tny_simple_list_new (); 
     57 * tny_msg_get_parts (message, parts); 
     58 * iter = tny_list_create_iterator (parts); 
     59 * while (!tny_iterator_is_done (iter)) 
     60 * { 
     61 *      TnyMimePart *part = TNY_MIME_PART (tny_iterator_get_current (iter)); 
     62 *      g_object_unref (G_OBJECT (part)); 
     63 *      tny_iterator_next (iter); 
     64 * } 
     65 * g_object_unref (G_OBJECT (iter)); 
     66 * g_object_unref (G_OBJECT (parts)); 
     67 * </programlisting></informalexample> 
    5268 * 
    5369 **/ 

  • trunk/libtinymailui-gtk/tny-gtk-msg-view.c

    r906 r908  
    9393        gtk_widget_hide (priv->attachview_sw); 
    9494        gtk_text_buffer_set_text (buffer, "", 0); 
    95  
    9695     
    9796        gtk_widget_show (GTK_WIDGET (priv->headerview)); 

  • trunk/libtinymailui-gtk/tny-gtk-save-strategy.c

    r900 r908  
    8181        if (fd != -1) 
    8282        { 
    83                 TnyFsStream *stream = NULL; 
    84                 stream = tny_fs_stream_new (fd); 
     83                TnyStream *stream = tny_fs_stream_new (fd); 
    8584                tny_mime_part_decode_to_stream (part, TNY_STREAM (stream)); 
    8685 
    87                 /* This also closes the file descriptor (maybe it shouldn't?) */ 
     86                /* This also closes the file descriptor */ 
    8887                g_object_unref (G_OBJECT (stream)); 
    89  
    9088                return TRUE; 
    9189        } 

  • trunk/libtinymailui/tny-header-view.c

    r900 r908  
    2929 * Clear the view @self (show nothing) 
    3030 * 
    31  * Implementors:  this method should clear @self (display nothing) 
     31 * Implementors: this method should clear @self (display nothing, or display 
     32 * a picture with flowers and nude people if that is how your E-mail client 
     33 * indicates that there's no header loaded) 
    3234 *  
    3335 **/ 
    …… 
    5052 * @header: A #TnyHeader instace 
    5153 * 
    52  * Set header of the view @self (show nothing) 
     54 * Set header of the view @self 
    5355 *  
    5456 * Implementors: this method should cause the view @self to show the header 

  • trunk/libtinymailui/tny-msg-view.c

    r900 r908  
    2929 * Clear the view @self (show nothing) 
    3030 *  
    31  * Implementors: this method should clear @self (display nothing) 
     31 * Implementors: this method should clear @self (display nothing, or display 
     32 * a picture with flowers and nude people if that is how your E-mail client 
     33 * indicates that there's no message loaded) 
    3234 * 
    3335 **/ 
    …… 
    8183 * mime-part. 
    8284 * 
     85 * Example: 
     86 * <informalexample><programlisting> 
     87 * static void  
     88 * tny_my_msg_view_set_save_strategy (TnyMsgView *self_i, TnySaveStrategy *strat) 
     89 * { 
     90 *      TnyMyMsgView *self = TNY_MY_MSG_VIEW (self_i); 
     91 *      if (self->save_strategy) 
     92 *            g_object_unref (G_OBJECT (self->save_strategy)); 
     93 *      self->save_strategy = g_object_ref (G_OBJECT (strat)); 
     94 * } 
     95 * static void 
     96 * tny_my_msg_view_finalize (TnyMyMsgView *self) 
     97 * { 
     98 *      if (self->save_strategy)) 
     99 *              g_object_unref (G_OBJECT (self->save_strategy)); 
     100 * } 
     101 * </programlisting></informalexample> 
     102 * 
     103 * <informalexample><programlisting> 
     104 * static void  
     105 * tny_my_msg_view_on_save_clicked (TnyMsgView *self, TnyMimePart *attachment) 
     106 * { 
     107 *     TnyMyMsgView *self = TNY_MY_MSG_VIEW (self_i); 
     108 *     tny_save_strategy_save (self->save_strategy, attachment); 
     109 * } 
     110 * </programlisting></informalexample> 
     111 * 
    83112 * The idea is that devices can have a specific such strategy. For example a 
    84113 * strategy that sends it to another computer or a strategy that saves it to 
    …… 
    98127        return; 
    99128} 
    100  
    101  
    102129 
    103130 

  • trunk/libtinymailui/tny-save-strategy.c

    r900 r908  
    2929 * Performs the saving of a mime part 
    3030 * 
     31 * Example: 
     32 * <informalexample><programlisting> 
     33 * static void  
     34 * tny_my_msg_view_on_save_clicked (TnyMsgView *self_i, TnyMimePart *attachment) 
     35 * { 
     36 *     TnyMyMsgView *self = TNY_MY_MSG_VIEW (self_i); 
     37 *     tny_save_strategy_save (self->save_strategy, attachment); 
     38 * } 
     39 * </programlisting></informalexample> 
     40 * 
    3141 * Implementors: the idea is that devices can have a specific such strategy. 
    3242 * For example a strategy that sends it to another computer or a strategy that 
    3343 * saves it to a flash disk.  
     44 * 
     45 * Example: 
     46 * <informalexample><programlisting> 
     47 * static void 
     48 * tny_gtk_save_strategy_save (TnySaveStrategy *self, TnyMimePart *part) 
     49 * { 
     50 *      GtkFileChooserDialog *dialog; 
     51 *      dialog = GTK_FILE_CHOOSER_DIALOG  
     52 *            (gtk_file_chooser_dialog_new (_("Save File"), NULL, 
     53 *            GTK_FILE_CHOOSER_ACTION_SAVE, 
     54 *            GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL, GTK_STOCK_SAVE,  
     55 *            GTK_RESPONSE_ACCEPT, NULL)); 
     56 *      gtk_file_chooser_set_current_name (dialog,  
     57 *            tny_mime_part_get_filename (part)); 
     58 *      if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT) { 
     59 *            gchar *uri; int fd; 
     60 *            uri = gtk_file_chooser_get_filename (dialog); 
     61 *            fd = open (uri, O_WRONLY|O_CREAT, S_IRUSR|S_IWUSR); 
     62 *            if (fd != -1) { 
     63 *                      TnyStream *stream = tny_fs_stream_new (fd); 
     64 *                      tny_mime_part_decode_to_stream (part, TNY_STREAM (stream)); 
     65 *                      g_object_unref (G_OBJECT (stream)); 
     66 *            }          
     67 *      } 
     68 *      gtk_widget_destroy (GTK_WIDGET (dialog)); 
     69 * } 
     70 * </programlisting></informalexample> 
    3471 * 
    3572 * The method is typically called by the implementation of a #TnyMsgView. 

  • trunk/tinymail/tny-demoui-summary-view.c

    r906 r908  
    122122        GtkTreeModel *sortable; 
    123123 
    124         /* TnyAccountTreeModel is also a TnyList (it simply both the 
    125            TnyList and the GtkTreeModel interfaces interfaces) */ 
     124        /* TnyAccountTreeModel is also a TnyList (it simply implements both the 
     125           TnyList and the GtkTreeModel interfaces) */ 
    126126 
    127127        GtkTreeModel *mailbox_model = tny_gtk_account_tree_model_new ();