/* -*- mode: C; c-file-style: "gnu" -*- */

/* dbus-string.c String utility class (internal to D-Bus implementation)

 * 

 * Copyright (C) 2002, 2003, 2004, 2005 Red Hat, Inc.

 * Portion Copyright © 2008 Nokia Corporation and/or its subsidiary(-ies). All rights reserved.

 * Licensed under the Academic Free License version 2.1

 * 

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation; either version 2 of the License, or

 * (at your option) any later version.

 *

 * This program 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 General Public License for more details.

 * 

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 *

 */

#include "dbus-internals.h"

#include "dbus-string.h"

/* we allow a system header here, for speed/convenience */

#include <string.h>

/* for vsnprintf */

#include <stdio.h>

#define DBUS_CAN_USE_DBUS_STRING_PRIVATE 1

#include "dbus-string-private.h"

#include "dbus-marshal-basic.h" /* probably should be removed by moving the usage of DBUS_TYPE

                                 * into the marshaling-related files

                                 */

/* for DBUS_VA_COPY */

#include "dbus-sysdeps.h"

/**

 * @defgroup DBusString DBusString class

 * @ingroup  DBusInternals

 * @brief DBusString data structure for safer string handling

 *

 * Types and functions related to DBusString. DBusString is intended

 * to be a string class that makes it hard to mess up security issues

 * (and just in general harder to write buggy code).  It should be

 * used (or extended and then used) rather than the libc stuff in

 * string.h.  The string class is a bit inconvenient at spots because

 * it handles out-of-memory failures and tries to be extra-robust.

 * 

 * A DBusString has a maximum length set at initialization time; this

 * can be used to ensure that a buffer doesn't get too big.  The

 * _dbus_string_lengthen() method checks for overflow, and for max

 * length being exceeded.

 * 

 * Try to avoid conversion to a plain C string, i.e. add methods on

 * the string object instead, only convert to C string when passing

 * things out to the public API. In particular, no sprintf, strcpy,

 * strcat, any of that should be used. The GString feature of

 * accepting negative numbers for "length of string" is also absent,

 * because it could keep us from detecting bogus huge lengths. i.e. if

 * we passed in some bogus huge length it would be taken to mean

 * "current length of string" instead of "broken crack"

 *

 * @todo #DBusString needs a lot of cleaning up; some of the

 * API is no longer used, and the API is pretty inconsistent.

 * In particular all the "append" APIs, especially those involving

 * alignment but probably lots of them, are no longer used by the

 * marshaling code which always does "inserts" now.

 */

/**

 * @addtogroup DBusString

 * @{

 */

static void

fixup_alignment (DBusRealString *real)

{

  unsigned char *aligned;

  unsigned char *real_block;

  unsigned int old_align_offset;

  /* we have to have extra space in real->allocated for the align offset and nul byte */

  _dbus_assert (real->len <= real->allocated - _DBUS_STRING_ALLOCATION_PADDING);

  old_align_offset = real->align_offset;

  real_block = real->str - old_align_offset;

  aligned = _DBUS_ALIGN_ADDRESS (real_block, 8);

  real->align_offset = aligned - real_block;

  real->str = aligned;

  if (old_align_offset != real->align_offset)

    {

      /* Here comes the suck */

      memmove (real_block + real->align_offset,

               real_block + old_align_offset,

               real->len + 1);

    }

  _dbus_assert (real->align_offset < 8);

  _dbus_assert (_DBUS_ALIGN_ADDRESS (real->str, 8) == real->str);

}

static void

undo_alignment (DBusRealString *real)

{

  if (real->align_offset != 0)

    {

      memmove (real->str - real->align_offset,

               real->str,

               real->len + 1);

      real->str = real->str - real->align_offset;

      real->align_offset = 0;

    }

}

/**

 * Initializes a string that can be up to the given allocation size

 * before it has to realloc. The string starts life with zero length.

 * The string must eventually be freed with _dbus_string_free().

 * 

 * @param str memory to hold the string

 * @param allocate_size amount to preallocate

 * @returns #TRUE on success, #FALSE if no memory

 */

dbus_bool_t

_dbus_string_init_preallocated (DBusString *str,

                                int         allocate_size)

{

  DBusRealString *real;

  _dbus_assert (str != NULL);

  _dbus_assert (sizeof (DBusString) == sizeof (DBusRealString));

  real = (DBusRealString*) str;

  /* It's very important not to touch anything

   * other than real->str if we're going to fail,

   * since we also use this function to reset

   * an existing string, e.g. in _dbus_string_steal_data()

   */

  real->str = dbus_malloc (_DBUS_STRING_ALLOCATION_PADDING + allocate_size);

  if (real->str == NULL)

    return FALSE;  

  real->allocated = _DBUS_STRING_ALLOCATION_PADDING + allocate_size;

  real->len = 0;

  real->str[real->len] = '\0';

  real->max_length = _DBUS_STRING_MAX_MAX_LENGTH;

  real->constant = FALSE;

  real->locked = FALSE;

  real->invalid = FALSE;

  real->align_offset = 0;

  fixup_alignment (real);

  return TRUE;

}

/**

 * Initializes a string. The string starts life with zero length.  The

 * string must eventually be freed with _dbus_string_free().

 * 

 * @param str memory to hold the string

 * @returns #TRUE on success, #FALSE if no memory

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

dbus_bool_t

_dbus_string_init (DBusString *str)

{

  return _dbus_string_init_preallocated (str, 0);

}

#ifdef DBUS_BUILD_TESTS

/* The max length thing is sort of a historical artifact

 * from a feature that turned out to be dumb; perhaps

 * we should purge it entirely. The problem with

 * the feature is that it looks like memory allocation

 * failure, but is not a transient or resolvable failure.

 */

static void

set_max_length (DBusString *str,

                int         max_length)

{

  DBusRealString *real;

  real = (DBusRealString*) str;

  real->max_length = max_length;

}

#endif /* DBUS_BUILD_TESTS */

/**

 * Initializes a constant string. The value parameter is not copied

 * (should be static), and the string may never be modified.

 * It is safe but not necessary to call _dbus_string_free()

 * on a const string. The string has a length limit of MAXINT - 8.

 * 

 * @param str memory to use for the string

 * @param value a string to be stored in str (not copied!!!)

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

_dbus_string_init_const (DBusString *str,

                         const char *value)

{

  _dbus_assert (value != NULL);

  _dbus_string_init_const_len (str, value,

                               strlen (value));

}

/**

 * Initializes a constant string with a length. The value parameter is

 * not copied (should be static), and the string may never be

 * modified.  It is safe but not necessary to call _dbus_string_free()

 * on a const string.

 * 

 * @param str memory to use for the string

 * @param value a string to be stored in str (not copied!!!)

 * @param len the length to use

 */

void

_dbus_string_init_const_len (DBusString *str,

                             const char *value,

                             int         len)

{

  DBusRealString *real;

  _dbus_assert (str != NULL);

  _dbus_assert (len == 0 || value != NULL);

  _dbus_assert (len <= _DBUS_STRING_MAX_MAX_LENGTH);

  _dbus_assert (len >= 0);

  real = (DBusRealString*) str;

  real->str = (unsigned char*) value;

  real->len = len;

  real->allocated = real->len + _DBUS_STRING_ALLOCATION_PADDING; /* a lie, just to avoid special-case assertions... */

  real->max_length = real->len + 1;

  real->constant = TRUE;

  real->locked = TRUE;

  real->invalid = FALSE;

  real->align_offset = 0;

  /* We don't require const strings to be 8-byte aligned as the

   * memory is coming from elsewhere.

   */

}

/**

 * Frees a string created by _dbus_string_init().

 *

 * @param str memory where the string is stored.

 */

 #ifdef __SYMBIAN32__

 EXPORT_C

 #endif

void

_dbus_string_free (DBusString *str)

{

  DBusRealString *real = (DBusRealString*) str;

  DBUS_GENERIC_STRING_PREAMBLE (real);

  if (real->constant)

    return;

  dbus_free (real->str - real->align_offset);

  real->invalid = TRUE;

}

#ifdef DBUS_BUILD_TESTS

/* Not using this feature at the moment,

 * so marked DBUS_BUILD_TESTS-only

 */

/**

 * Locks a string such that any attempts to change the string will

 * result in aborting the program. Also, if the string is wasting a

 * lot of memory (allocation is sufficiently larger than what the

 * string is really using), _dbus_string_lock() will realloc the

 * string's data to "compact" it.

 *

 * @param str the string to lock.

 */

void

_dbus_string_lock (DBusString *str)

{  

  DBUS_LOCKED_STRING_PREAMBLE (str); /* can lock multiple times */

  real->locked = TRUE;

  /* Try to realloc to avoid excess memory usage, since

   * we know we won't change the string further

   */

#define MAX_WASTE 48

  if (real->allocated - MAX_WASTE > real->len)

    {

      unsigned char *new_str;

      int new_allocated;

      new_allocated = real->len + _DBUS_STRING_ALLOCATION_PADDING;

      new_str = dbus_realloc (real->str - real->align_offset,

                              new_allocated);

      if (new_str != NULL)

        {

          real->str = new_str + real->align_offset;

          real->allocated = new_allocated;

          fixup_alignment (real);

        }

    }

}

#endif /* DBUS_BUILD_TESTS */

static dbus_bool_t

reallocate_for_length (DBusRealString *real,

                       int             new_length)

{

  int new_allocated;

  unsigned char *new_str;

  /* at least double our old allocation to avoid O(n), avoiding

   * overflow

   */

  if (real->allocated > (_DBUS_STRING_MAX_MAX_LENGTH + _DBUS_STRING_ALLOCATION_PADDING) / 2)

    new_allocated = _DBUS_STRING_MAX_MAX_LENGTH + _DBUS_STRING_ALLOCATION_PADDING;

  else

    new_allocated = real->allocated * 2;

  /* if you change the code just above here, run the tests without

   * the following assert-only hack before you commit

   */

  /* This is keyed off asserts in addition to tests so when you

   * disable asserts to profile, you don't get this destroyer

   * of profiles.

   */

#ifdef DBUS_DISABLE_ASSERT

#else

#ifdef DBUS_BUILD_TESTS

  new_allocated = 0; /* ensure a realloc every time so that we go

                      * through all malloc failure codepaths

                      */

#endif /* DBUS_BUILD_TESTS */

#endif /* !DBUS_DISABLE_ASSERT */

  /* But be sure we always alloc at least space for the new length */

  new_allocated = MAX (new_allocated,

                       new_length + _DBUS_STRING_ALLOCATION_PADDING);

  _dbus_assert (new_allocated >= real->allocated); /* code relies on this */

  new_str = dbus_realloc (real->str - real->align_offset, new_allocated);

  if (_DBUS_UNLIKELY (new_str == NULL))

    return FALSE;

  real->str = new_str + real->align_offset;

  real->allocated = new_allocated;

  fixup_alignment (real);

  return TRUE;

}

static dbus_bool_t

set_length (DBusRealString *real,

            int             new_length)

{

  /* Note, we are setting the length not including nul termination */

  /* exceeding max length is the same as failure to allocate memory */

  if (_DBUS_UNLIKELY (new_length > real->max_length))

    return FALSE;

  else if (new_length > (real->allocated - _DBUS_STRING_ALLOCATION_PADDING) &&

           _DBUS_UNLIKELY (!reallocate_for_length (real, new_length)))

    return FALSE;

  else

    {

      real->len = new_length;

      real->str[new_length] = '\0';

      return TRUE;

    }

}

static dbus_bool_t

open_gap (int             len,

          DBusRealString *dest,

          int             insert_at)

{

  if (len == 0)

    return TRUE;

  if (len > dest->max_length - dest->len)

    return FALSE; /* detected overflow of dest->len + len below */

  if (!set_length (dest, dest->len + len))

    return FALSE;

  memmove (dest->str + insert_at + len, 

           dest->str + insert_at,

           dest->len - len - insert_at);

  return TRUE;

}

#ifndef _dbus_string_get_data

/**

 * Gets the raw character buffer from the string.  The returned buffer

 * will be nul-terminated, but note that strings may contain binary

 * data so there may be extra nul characters prior to the termination.

 * This function should be little-used, extend DBusString or add

 * stuff to dbus-sysdeps.c instead. It's an error to use this

 * function on a const string.

 *

 * @param str the string

 * @returns the data

 */

char*

_dbus_string_get_data (DBusString *str)

{

  DBUS_STRING_PREAMBLE (str);

  return (char*) real->str;

}

#endif /* _dbus_string_get_data */

/* only do the function if we don't have the macro */

#ifndef _dbus_string_get_const_data

/**

 * Gets the raw character buffer from a const string.

 *

 * @param str the string

 * @returns the string data

 */

const char*

_dbus_string_get_const_data (const DBusString  *str)

{

  DBUS_CONST_STRING_PREAMBLE (str);

  return (const char*) real->str;

}

#endif /* _dbus_string_get_const_data */

/**

 * Gets a sub-portion of the raw character buffer from the

 * string. The "len" field is required simply for error

 * checking, to be sure you don't try to use more

 * string than exists. The nul termination of the

 * returned buffer remains at the end of the entire

 * string, not at start + len.

 *

 * @param str the string

 * @param start byte offset to return

 * @param len length of segment to return

 * @returns the string data

 */

char*

_dbus_string_get_data_len (DBusString *str,

                           int         start,

                           int         len)

{

  DBUS_STRING_PREAMBLE (str);

  _dbus_assert (start >= 0);

  _dbus_assert (len >= 0);

  _dbus_assert (start <= real->len);

  _dbus_assert (len <= real->len - start);

  return (char*) real->str + start;

}

/* only do the function if we don't have the macro */

#ifndef _dbus_string_get_const_data_len

/**

 * const version of _dbus_string_get_data_len().

 *

 * @param str the string

 * @param start byte offset to return

 * @param len length of segment to return

 * @returns the string data

 */

const char*

_dbus_string_get_const_data_len (const DBusString  *str,

                                 int                start,

                                 int                len)

{

  DBUS_CONST_STRING_PREAMBLE (str);

  _dbus_assert (start >= 0);

  _dbus_assert (len >= 0);

  _dbus_assert (start <= real->len);

  _dbus_assert (len <= real->len - start);

  return (const char*) real->str + start;

}

#endif /* _dbus_string_get_const_data_len */

/* only do the function if we don't have the macro */

#ifndef _dbus_string_set_byte

/**

 * Sets the value of the byte at the given position.

 *

 * @param str the string

 * @param i the position

 * @param byte the new value

 */

void

_dbus_string_set_byte (DBusString    *str,

                       int            i,

                       unsigned char  byte)

{

  DBUS_STRING_PREAMBLE (str);

  _dbus_assert (i < real->len);

  _dbus_assert (i >= 0);