document dc_str_unref()

deltachat-ffi/deltachat.h

@@ -134,7 +134,7 @@ typedef struct _dc_provider dc_provider_t;
  *
  *     printf("Message %i: %s\n", i+1, text);
  *
- *     free(text);
+ *     dc_str_unref(text);
  *     dc_msg_unref(msg);
  * }
  * dc_array_unref(msglist);
@@ -320,7 +320,7 @@ int             dc_is_open                   (const dc_context_t* context);
  * @memberof dc_context_t
  * @param context The context object as created by dc_context_new().
  * @return Blob directory associated with the context object, empty string if unset or on errors. NULL is never returned.
- *     The returned string must be free()'d.
+ *     The returned string must be released using dc_str_unref().
  */
 char*           dc_get_blobdir               (const dc_context_t* context);
 
@@ -396,7 +396,7 @@ int             dc_set_config                (dc_context_t* context, const char*
  * @param context The context object as created by dc_context_new(). For querying system values, this can be NULL.
  * @param key The key to query.
  * @return Returns current value of "key", if "key" is unset, the default
- *     value is returned.  The returned value must be free()'d, NULL is never
+ *     value is returned.  The returned value must be released using dc_str_unref(), NULL is never
  *     returned.  If there is an error an empty string will be returned.
  */
 char*           dc_get_config                (dc_context_t* context, const char* key);
@@ -427,7 +427,7 @@ int             dc_set_stock_translation(dc_context_t* context, uint32_t stock_i
  *
  * @memberof dc_context_t
  * @param context The context as created by dc_context_new().
- * @return String which must be free()'d after usage.  Never returns NULL.
+ * @return String which must be released using dc_str_unref() after usage.  Never returns NULL.
  */
 char*           dc_get_info                  (dc_context_t* context);
 
@@ -458,6 +458,7 @@ char*           dc_get_info                  (dc_context_t* context);
  *     `https://localhost:PORT/PATH`, `urn:ietf:wg:oauth:2.0:oob`
  *     (the latter just displays the code the user can copy+paste then)
  * @return URL that can be opened in the browser to start OAuth2.
+ *     Returned strings must be released using dc_str_unref().
  *     If OAuth2 is not possible for the given e-mail-address, NULL is returned.
  */
 char*           dc_get_oauth2_url            (dc_context_t* context, const char* addr, const char* redirect_uri);
@@ -706,6 +707,7 @@ void            dc_perform_mvbox_idle        (dc_context_t* context);
  */
 void            dc_interrupt_mvbox_idle      (dc_context_t* context);
 
+
 /**
  * Execute pending sentbox-jobs.
  * This function and dc_perform_sentbox_fetch() and dc_perform_sentbox_idle()
@@ -1477,7 +1479,7 @@ int             dc_set_chat_profile_image    (dc_context_t* context, uint32_t ch
  * @memberof dc_context_t
  * @param context The context object as created by dc_context_new().
  * @param msg_id The message id for which information should be generated
- * @return Text string, must be free()'d after usage
+ * @return Text string, must be released using dc_str_unref() after usage
  */
 char*           dc_get_msg_info              (dc_context_t* context, uint32_t msg_id);
 
@@ -1491,7 +1493,7 @@ char*           dc_get_msg_info              (dc_context_t* context, uint32_t ms
  * @memberof dc_context_t
  * @param context The context object as created by dc_context_new().
  * @param msg_id The message id, must be the id of an incoming message.
- * @return Raw headers as a multi-line string, must be free()'d after usage.
+ * @return Raw headers as a multi-line string, must be released using dc_str_unref() after usage.
  *     Returns NULL if there are no headers saved for the given message,
  *     eg. because of save_mime_headers is not set
  *     or the message is not incoming.
@@ -1732,7 +1734,7 @@ void            dc_block_contact             (dc_context_t* context, uint32_t co
  * @memberof dc_context_t
  * @param context The context object as created by dc_context_new().
  * @param contact_id ID of the contact to get the encryption info for.
- * @return Multi-line text, must be free()'d after usage.
+ * @return Multi-line text, must be released using dc_str_unref() after usage.
  */
 char*           dc_get_contact_encrinfo      (dc_context_t* context, uint32_t contact_id);
 
@@ -1868,7 +1870,8 @@ void            dc_imex                      (dc_context_t* context, int what, c
  * @memberof dc_context_t
  * @param context The context as created by dc_context_new().
  * @param dir Directory to search backups in.
- * @return String with the backup file, typically given to dc_imex(), returned strings must be free()'d.
+ * @return String with the backup file, typically given to dc_imex(),
+ *     returned strings must be released using dc_str_unref().
  *     The function returns NULL if no backup was found.
  */
 char*           dc_imex_has_backup           (dc_context_t* context, const char* dir);
@@ -1916,7 +1919,7 @@ char*           dc_imex_has_backup           (dc_context_t* context, const char*
  *
  * @memberof dc_context_t
  * @param context The context object.
- * @return The setup code. Must be free()'d after usage.
+ * @return The setup code. Must be released using dc_str_unref() after usage.
  *     On errors, eg. if the message could not be sent, NULL is returned.
  */
 char*           dc_initiate_key_transfer     (dc_context_t* context);
@@ -2021,7 +2024,7 @@ dc_lot_t*       dc_check_qr                  (dc_context_t* context, const char*
  *     If set to 0, the setup-Verified-contact-protocol is offered in the QR code.
  * @return Text that should go to the QR code,
  *     On errors, an empty QR code is returned, NULL is never returned.
- *     The returned string must be free()'d after usage.
+ *     The returned string must be released using dc_str_unref() after usage.
  */
 char*           dc_get_securejoin_qr         (dc_context_t* context, uint32_t chat_id);
 
@@ -2191,6 +2194,21 @@ dc_array_t* dc_get_locations                (dc_context_t* context, uint32_t cha
 void        dc_delete_all_locations         (dc_context_t* context);
 
 
+/**
+ * Release a string returned by another deltachat-core function.
+ * - Strings returned by any deltachat-core-function
+ *   MUST NOT be released by the standard free() function;
+ *   always use dc_str_unref() for this purpose.
+ * - dc_str_unref() MUST NOT be called for strings not returned by deltachat-core.
+ * - dc_str_unref() MUST NOT be called for other objectes returned by deltachat-core.
+ *
+ * @memberof dc_context_t
+ * @param str The string to release.
+ * @return None.
+ */
+void dc_str_unref (char* str);
+
+
 /**
  * @class dc_array_t
  *
@@ -2331,7 +2349,7 @@ uint32_t         dc_array_get_msg_id         (const dc_array_t* array, size_t in
  * @param index Index of the item. Must be between 0 and dc_array_get_cnt()-1.
  * @return Marker-character of the item at the given index.
  *     NULL if there is no marker-character bound to the given item.
- *     The returned value must be free()'d after usage.
+ *     The returned value must be released using dc_str_unref() after usage.
  */
 char*            dc_array_get_marker         (const dc_array_t* array, size_t index);
 
@@ -2586,7 +2604,7 @@ int             dc_chat_get_type             (const dc_chat_t* chat);
  *
  * @memberof dc_chat_t
  * @param chat The chat object.
- * @return Chat name as a string. Must be free()'d after usage. Never NULL.
+ * @return Chat name as a string. Must be released using dc_str_unref() after usage. Never NULL.
  */
 char*           dc_chat_get_name             (const dc_chat_t* chat);
 
@@ -2599,7 +2617,7 @@ char*           dc_chat_get_name             (const dc_chat_t* chat);
  *
  * @memberof dc_chat_t
  * @param chat The chat object to calulate the subtitle for.
- * @return Subtitle as a string. Must be free()'d after usage. Never NULL.
+ * @return Subtitle as a string. Must be released using dc_str_unref() after usage. Never NULL.
  */
 char*           dc_chat_get_subtitle         (const dc_chat_t* chat);
 
@@ -2615,7 +2633,7 @@ char*           dc_chat_get_subtitle         (const dc_chat_t* chat);
  * @param chat The chat object.
  * @return Path and file if the profile image, if any.
  *     NULL otherwise.
- *     Must be free()'d after usage.
+ *     Must be released using dc_str_unref() after usage.
  */
 char*           dc_chat_get_profile_image    (const dc_chat_t* chat);
 
@@ -2919,7 +2937,7 @@ int64_t          dc_msg_get_sort_timestamp     (const dc_msg_t* msg);
  *
  * @memberof dc_msg_t
  * @param msg The message object.
- * @return Message text. The result must be free()'d. Never returns NULL.
+ * @return Message text. The result must be released using dc_str_unref(). Never returns NULL.
  */
 char*           dc_msg_get_text               (const dc_msg_t* msg);
 
@@ -2933,9 +2951,9 @@ char*           dc_msg_get_text               (const dc_msg_t* msg);
  *
  * @memberof dc_msg_t
  * @param msg The message object.
- * @return Full path, file name and extension of the file associated with the
+ * @return Full path, file name and extension of the file associated with the message.
- *     message.  If there is no file associated with the message, an emtpy
+ *     If there is no file associated with the message, an emtpy string is returned.
- *     string is returned.  NULL is never returned and the returned value must be free()'d.
+ *     NULL is never returned and the returned value must be released using dc_str_unref().
  */
 char*           dc_msg_get_file               (const dc_msg_t* msg);
 
@@ -2948,7 +2966,7 @@ char*           dc_msg_get_file               (const dc_msg_t* msg);
  * @param msg The message object.
  * @return Base file name plus extension without part.  If there is no file
  *     associated with the message, an empty string is returned.  The returned
- *     value must be free()'d.
+ *     value must be released using dc_str_unref().
  */
 char*           dc_msg_get_filename           (const dc_msg_t* msg);
 
@@ -2960,7 +2978,8 @@ char*           dc_msg_get_filename           (const dc_msg_t* msg);
  *
  * @memberof dc_msg_t
  * @param msg The message object.
- * @return String containing the mime type. Must be free()'d after usage. NULL is never returned.
+ * @return String containing the mime type.
+ *     Must be released using dc_str_unref() after usage. NULL is never returned.
  */
 char*           dc_msg_get_filemime           (const dc_msg_t* msg);
 
@@ -3068,7 +3087,8 @@ dc_lot_t*       dc_msg_get_summary            (const dc_msg_t* msg, const dc_cha
  * @memberof dc_msg_t
  * @param msg The message object.
  * @param approx_characters Rough length of the expected string.
- * @return A summary for the given messages. The returned string must be free()'d.
+ * @return A summary for the given messages.
+ *     The returned string must be released using dc_str_unref().
  *     Returns an empty string on errors, never returns NULL.
  */
 char*           dc_msg_get_summarytext        (const dc_msg_t* msg, int approx_characters);
@@ -3213,7 +3233,7 @@ int             dc_msg_is_setupmessage        (const dc_msg_t* msg);
  * @memberof dc_msg_t
  * @param msg The message object.
  * @return Typically, the first two digits of the setup code or an empty string if unknown.
- *     NULL is never returned. Must be free()'d when done.
+ *     NULL is never returned. Must be released using dc_str_unref() when done.
  */
 char*           dc_msg_get_setupcodebegin     (const dc_msg_t* msg);
 
@@ -3370,7 +3390,8 @@ uint32_t        dc_contact_get_id            (const dc_contact_t* contact);
  *
  * @memberof dc_contact_t
  * @param contact The contact object.
- * @return String with the email address, must be free()'d. Never returns NULL.
+ * @return String with the email address,
+ *     must be released using dc_str_unref(). Never returns NULL.
  */
 char*           dc_contact_get_addr          (const dc_contact_t* contact);
 
@@ -3384,7 +3405,8 @@ char*           dc_contact_get_addr          (const dc_contact_t* contact);
  *
  * @memberof dc_contact_t
  * @param contact The contact object.
- * @return String with the name to display, must be free()'d. Empty string if unset, never returns NULL.
+ * @return String with the name to display, must be released using dc_str_unref().
+ *     Empty string if unset, never returns NULL.
  */
 char*           dc_contact_get_name          (const dc_contact_t* contact);
 
@@ -3398,7 +3420,8 @@ char*           dc_contact_get_name          (const dc_contact_t* contact);
  *
  * @memberof dc_contact_t
  * @param contact The contact object.
- * @return String with the name to display, must be free()'d. Never returns NULL.
+ * @return String with the name to display, must be released using dc_str_unref().
+ *     Never returns NULL.
  */
 char*           dc_contact_get_display_name  (const dc_contact_t* contact);
 
@@ -3414,7 +3437,8 @@ char*           dc_contact_get_display_name  (const dc_contact_t* contact);
  *
  * @memberof dc_contact_t
  * @param contact The contact object.
- * @return Summary string, must be free()'d. Never returns NULL.
+ * @return Summary string, must be released using dc_str_unref().
+ *     Never returns NULL.
  */
 char*           dc_contact_get_name_n_addr   (const dc_contact_t* contact);
 
@@ -3426,7 +3450,8 @@ char*           dc_contact_get_name_n_addr   (const dc_contact_t* contact);
  *
  * @memberof dc_contact_t
  * @param contact The contact object.
- * @return String with the name to display, must be free()'d. Never returns NULL.
+ * @return String with the name to display, must be released using dc_str_unref().
+ *     Never returns NULL.
  */
 char*           dc_contact_get_first_name    (const dc_contact_t* contact);
 
@@ -3440,7 +3465,7 @@ char*           dc_contact_get_first_name    (const dc_contact_t* contact);
  * @param contact The contact object.
  * @return Path and file if the profile image, if any.
  *     NULL otherwise.
- *     Must be free()'d after usage.
+ *     Must be released using dc_str_unref() after usage.
  */
 char*           dc_contact_get_profile_image (const dc_contact_t* contact);
 
@@ -3521,7 +3546,7 @@ dc_provider_t*  dc_provider_new_from_email            (const char* email);
  *
  * @memberof dc_provider_t
  * @param provider The dc_provider_t struct.
- * @return A string which must be free()d.
+ * @return A string which must be released using dc_str_unref().
  */
 char*           dc_provider_get_overview_page         (const dc_provider_t* provider);
 
@@ -3533,7 +3558,7 @@ char*           dc_provider_get_overview_page         (const dc_provider_t* prov
  *
  * @memberof dc_provider_t
  * @param provider The dc_provider_t struct.
- * @return A string which must be free()d.
+ * @return A string which must be released using dc_str_unref().
  */
 char*           dc_provider_get_name                  (const dc_provider_t* provider);
 
@@ -3546,7 +3571,7 @@ char*           dc_provider_get_name                  (const dc_provider_t* prov
  *
  * @memberof dc_provider_t
  * @param provider The dc_provider_t struct.
- * @return A string which must be free()d.
+ * @return A string which must be released using dc_str_unref().
  */
 char*           dc_provider_get_markdown              (const dc_provider_t* provider);
 
@@ -3558,7 +3583,7 @@ char*           dc_provider_get_markdown              (const dc_provider_t* prov
  *
  * @memberof dc_provider_t
  * @param provider The dc_provider_t struct.
- * @return A string which must be free()d.
+ * @return A string which must be released using dc_str_unref().
  */
 char*           dc_provider_get_status_date           (const dc_provider_t* provider);
 
@@ -3620,7 +3645,9 @@ void            dc_lot_unref             (dc_lot_t* lot);
  *
  * @memberof dc_lot_t
  * @param lot The lot object.
- * @return A string, the string may be empty and the returned value must be free()'d. NULL if there is no such string.
+ * @return A string, the string may be empty
+ *     and the returned value must be released using dc_str_unref().
+ *     NULL if there is no such string.
  */
 char*           dc_lot_get_text1         (const dc_lot_t* lot);
 
@@ -3629,10 +3656,10 @@ char*           dc_lot_get_text1         (const dc_lot_t* lot);
  * Get second string. The meaning of the string is defined by the creator of the object.
  *
  * @memberof dc_lot_t
- *
  * @param lot The lot object.
- *
+ * @return A string, the string may be empty
- * @return A string, the string may be empty and the returned value must be free()'d	. NULL if there is no such string.
+ *     and the returned value must be released using dc_str_unref().
+ *     NULL if there is no such string.
  */
 char*           dc_lot_get_text2         (const dc_lot_t* lot);
 
@@ -3653,9 +3680,7 @@ int             dc_lot_get_text1_meaning (const dc_lot_t* lot);
  * Get the associated state. The meaning of the state is defined by the creator of the object.
  *
  * @memberof dc_lot_t
- *
  * @param lot The lot object.
- *
  * @return The state as defined by the creator of the object. 0 if there is not state or on errors.
  */
 int             dc_lot_get_state         (const dc_lot_t* lot);
@@ -3677,9 +3702,7 @@ uint32_t        dc_lot_get_id            (const dc_lot_t* lot);
  * The meaning of the timestamp is defined by the creator of the object.
  *
  * @memberof dc_lot_t
- *
  * @param lot The lot object.
- *
  * @return The timestamp as defined by the creator of the object. 0 if there is not timestamp or on errors.
  */
 int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
@@ -3879,7 +3902,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) Info string in english language.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_INFO                     100
@@ -3890,7 +3913,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) Info string in english language.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_SMTP_CONNECTED           101
@@ -3901,7 +3924,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) Info string in english language.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_IMAP_CONNECTED           102
@@ -3911,7 +3934,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) Info string in english language.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_SMTP_MESSAGE_SENT        103
@@ -3921,7 +3944,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) Info string in english language.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_IMAP_MESSAGE_DELETED   104
@@ -3931,7 +3954,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) Info string in english language.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_IMAP_MESSAGE_MOVED   105
@@ -3941,7 +3964,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) path name 
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_NEW_BLOB_FILE 150
@@ -3951,7 +3974,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) path name 
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_DELETED_BLOB_FILE 151
@@ -3964,7 +3987,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) Warning string in english language.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_WARNING                  300
@@ -3987,7 +4010,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  * @param data2 (const char*) Error string, always set, never NULL.
  *     Some error strings are taken from dc_set_stock_translation(),
  *     however, most error strings will be in english language.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_ERROR                    400
@@ -4011,7 +4034,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  * @param data1 (int) 1=first/new network error, should be reported the user;
  *     0=subsequent network error, should be logged only
  * @param data2 (const char*) Error string, always set, never NULL.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @return 0
  */
 #define DC_EVENT_ERROR_NETWORK            401
@@ -4026,7 +4049,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  *
  * @param data1 0
  * @param data2 (const char*) Info string in english language.
- *     Must not be free()'d or modified
+ *     Must not be released or modified
  *     and is valid only until the callback returns.
  * @return 0
  */
@@ -4157,7 +4180,7 @@ int64_t          dc_lot_get_timestamp     (const dc_lot_t* lot);
  * services.
  *
  * @param data1 (const char*) Path and file name.
- *     Must not be free()'d or modified and is valid only until the callback returns.
+ *     Must not be released or modified and is valid only until the callback returns.
  * @param data2 0
  * @return 0
  */
@@ -4317,9 +4340,6 @@ void            dc_array_add_id              (dc_array_t*, uint32_t); // depreca
 #define DC_STR_STICKER                    67
 #define DC_STR_COUNT                      67
 
-void dc_str_unref (char*);
-
-
 /*
  * @}
  */