<!--
  Copyright (C) 2015 William Yu <williamyu@gnome.org>
  
  This library is free software: you can redistribute it and/or modify it
  under the terms of version 2.1. of the GNU Lesser General Public License
  as published by the Free Software Foundation.
  
  This library is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
  for more details.
  
  You should have received a copy of the GNU Lesser General Public License
  along with this library. If not, see <http://www.gnu.org/licenses/>.
-->
<structure namespace="ICal" name="Memory">
    <method name="i_cal_memory_tmp_buffer" corresponds="icalmemory_tmp_buffer" since="1.0">
        <parameter type="size_t" name="size" comment="The size of the buffer to be created."/>
        <returns type="void *" annotation="transfer full" comment="The newly created buffer"/>
        <comment xml:space="preserve">Create a buffer with target size.</comment>
    </method>
    <method name="i_cal_memory_tmp_copy" corresponds="icalmemory_tmp_copy" since="1.0">
        <parameter type="const gchar *" name="str" comment="The string to be copied"/>
        <returns type="gchar *" annotation="transfer full" comment="The new copy of the @str."/>
        <comment xml:space="preserve">Like strdup, but the buffer is on the ring.</comment>
    </method>
    <method name="i_cal_memory_add_tmp_buffer" corresponds="icalmemory_add_tmp_buffer" since="1.0">
        <parameter type="void *" name="buf" annotation="transfer full" comment="The existing buffer to be added into the ical"/>
        <comment xml:space="preserve">Add an existing buffer to the buffer ring</comment>
    </method>
    <method name="i_cal_memory_free_ring" annotation="skip" corresponds="icalmemory_free_ring" since="1.0">
        <comment xml:space="preserve">Free all the memory used in the ring.</comment>
    </method>
    <method name="i_cal_memory_new_buffer" corresponds="icalmemory_new_buffer" since="1.0">
        <parameter type="size_t" name="size" comment="The size of the new buffer to be created."/>
        <returns type="void *" annotation="transfer full" comment="The newly created buffer with the target size."/>
        <comment xml:space="preserve">Create a new buffer with target size. The caller should deallocate it when necessary.</comment>
    </method>
    <method name="i_cal_memory_resize_buffer" corresponds="icalmemory_resize_buffer" since="1.0">
        <parameter type="void *" name="buf" annotation="transfer full" comment="The buffer needs to be resized."/>
        <parameter type="size_t" name="size" comment="The target size the buffer to be resized to."/>
        <returns type="void *" annotation="transfer full" comment="The buffer after being resized."/>
        <comment xml:space="preserve">Resize the buffer to the target size.</comment>
    </method>
    <method name="i_cal_memory_free_buffer" corresponds="icalmemory_free_buffer" since="1.0">
        <parameter type="void *" name="buf" annotation="transfer full" comment="The buffer to be freed."/>
        <comment xml:space="preserve">Free the buffer.</comment>
    </method>
    <method name="i_cal_memory_append_string" corresponds="icalmemory_append_string" since="1.0">
        <parameter type="gchar **" name="buf" comment="The buffer to be appended. It should not be the memory in ical."/>
        <parameter type="gchar **" name="pos" comment="The position at which the new string to be appended."/>
        <parameter type="size_t *" name="buf_size" comment="THe size of the buffer before appended"/>
        <parameter type="const gchar *" name="string" comment="The string to be allocated"/>
        <comment xml:space="preserve">Append the string to the buffer. Only use them on normally allocated memory, or on buffers created from icalmemory_new_buffer, never with buffers created by icalmemory_tmp_buffer. If icalmemory_append_string has to resize a buffer on the ring, the ring will loose track of it an you will have memory problems.</comment>
    </method>
    <method name="i_cal_memory_append_char" corresponds="icalmemory_append_char" since="1.0">
        <parameter type="gchar **" name="buf" comment="The buffer to be appended. It should not be the memory in ical."/>
        <parameter type="gchar **" name="pos" comment="The position at which the new string to be appended."/>
        <parameter type="size_t *" name="buf_size" comment="THe size of the buffer before appended"/>
        <parameter type="gchar" name="ch" comment="The character to be allocated"/>
        <comment xml:space="preserve">Append the character to the buffer. Only use them on normally allocated memory, or on buffers created from icalmemory_new_buffer, never with buffers created by icalmemory_tmp_buffer. If icalmemory_append_string has to resize a buffer on the ring, the ring will loose track of it an you will have memory problems.</comment>
    </method>
    <method name="i_cal_memory_strdup" corresponds="icalmemory_strdup" since="1.0">
        <parameter type="const gchar *" name="s" comment="The string to be cloned."/>
        <returns type="gchar *" annotation="transfer full" comment="The cloned string."/>
        <comment xml:space="preserve">A wrapper around strdup. Partly to trap calls to strdup, partly because in -ansi, gcc on Red Hat claims that strdup is undeclared</comment>
    </method>
</structure>
