clarify the usage and ownership of members of struct _message
authorLars Rohwedder <roker@pep-project.org>
Thu, 03 Mar 2016 14:27:42 +0100
changeset 4920c8bd44f2eb1
parent 491 d32c60ada438
child 495 79cdc1bcf26c
clarify the usage and ownership of members of struct _message
src/message.h
     1.1 --- a/src/message.h	Thu Mar 03 13:09:12 2016 +0100
     1.2 +++ b/src/message.h	Thu Mar 03 14:27:42 2016 +0100
     1.3 @@ -44,7 +44,7 @@
     1.4      char *longmsg_formatted;                // UTF-8 string of long message
     1.5                                              // (formatted)
     1.6      bloblist_t *attachments;                // blobs with attachements
     1.7 -    char *rawmsg_ref;                       // reference to raw message data
     1.8 +    char *rawmsg_ref;                       // reference to raw message data (NOT owned by struct _message, not used by pEpEngine)
     1.9      size_t rawmsg_size;                     // size of raw message data
    1.10      timestamp *sent;                        // when the message is sent
    1.11      timestamp *recv;                        // when the message is received
    1.12 @@ -91,9 +91,9 @@
    1.13  //  parameters:
    1.14  //      msg (in)        message struct to free
    1.15  //
    1.16 -//  caveat:
    1.17 -//      raw data as well as referenced other messages aren't freed and remain
    1.18 -//      in the ownership of the caller
    1.19 +//  NOTA BENE:
    1.20 +//      raw data (msg->rawmsg_ref) and referenced other messages (msg->refering_msg_ref)
    1.21 +//      aren't freed and remain in the ownership of the caller!
    1.22  
    1.23  DYNAMIC_API void free_message(message *msg);
    1.24  
    1.25 @@ -105,6 +105,8 @@
    1.26  //
    1.27  //  return value:
    1.28  //      pointer to duplicate of message pointed by msg or NULL
    1.29 +//  NOTA BENE:
    1.30 +//      not owned pointees (msg->rawmsg_ref and msg->refering_msg_ref) are shared!
    1.31  
    1.32  DYNAMIC_API message * message_dup(const message *msg);
    1.33