Main Page   Modules   Data Structures   File List   Data Fields   Related Pages  

string class
[D-BUS internal implementation details]

DBusString data structure. More...

Defines

#define DBUS_STRING_COPY_PREAMBLE(source, start, dest, insert_at)
 Checks assertions for two strings we're copying a segment between, and declares real_source/real_dest variables. More...

#define UTF8_COMPUTE(Char, Mask, Len)
 computes length and mask of a unicode character. More...

#define UTF8_LENGTH(Char)
 computes length of a unicode character in UTF-8. More...

#define UTF8_GET(Result, Chars, Count, Mask, Len)
 Gets a UTF-8 value. More...

#define UNICODE_VALID(Char)
 Check whether a unicode char is in a valid range. More...

#define VALID_INITIAL_NAME_CHARACTER(c)
 Determine wether the given charater is valid as the first charater in a name. More...

#define VALID_NAME_CHARACTER(c)
 Determine wether the given charater is valid as a second or later character in a nam. More...


Functions

dbus_bool_t _dbus_string_init_preallocated (DBusString *str, int allocate_size)
 Initializes a string that can be up to the given allocation size before it has to realloc. More...

dbus_bool_t _dbus_string_init (DBusString *str)
 Initializes a string. More...

void _dbus_string_init_const (DBusString *str, const char *value)
 Initializes a constant string. More...

void _dbus_string_init_const_len (DBusString *str, const char *value, int len)
 Initializes a constant string with a length. More...

void _dbus_string_free (DBusString *str)
 Frees a string created by _dbus_string_init(). More...

void _dbus_string_lock (DBusString *str)
 Locks a string such that any attempts to change the string will result in aborting the program. More...

char * _dbus_string_get_data (DBusString *str)
 Gets the raw character buffer from the string. More...

const char * _dbus_string_get_const_data (const DBusString *str)
 Gets the raw character buffer from a const string. More...

char * _dbus_string_get_data_len (DBusString *str, int start, int len)
 Gets a sub-portion of the raw character buffer from the string. More...

const char * _dbus_string_get_const_data_len (const DBusString *str, int start, int len)
 const version of _dbus_string_get_data_len(). More...

void _dbus_string_set_byte (DBusString *str, int i, unsigned char byte)
 Sets the value of the byte at the given position. More...

unsigned char _dbus_string_get_byte (const DBusString *str, int start)
 Gets the byte at the given position. More...

dbus_bool_t _dbus_string_insert_bytes (DBusString *str, int i, int n_bytes, unsigned char byte)
 Inserts a number of bytes of a given value at the given position. More...

dbus_bool_t _dbus_string_steal_data (DBusString *str, char **data_return)
 Like _dbus_string_get_data(), but removes the gotten data from the original string. More...

dbus_bool_t _dbus_string_steal_data_len (DBusString *str, char **data_return, int start, int len)
 Like _dbus_string_get_data_len(), but removes the gotten data from the original string. More...

dbus_bool_t _dbus_string_copy_data (const DBusString *str, char **data_return)
 Copies the data from the string into a char*. More...

dbus_bool_t _dbus_string_copy_data_len (const DBusString *str, char **data_return, int start, int len)
 Copies a segment of the string into a char*. More...

int _dbus_string_get_length (const DBusString *str)
 Gets the length of a string (not including nul termination). More...

dbus_bool_t _dbus_string_lengthen (DBusString *str, int additional_length)
 Makes a string longer by the given number of bytes. More...

void _dbus_string_shorten (DBusString *str, int length_to_remove)
 Makes a string shorter by the given number of bytes. More...

dbus_bool_t _dbus_string_set_length (DBusString *str, int length)
 Sets the length of a string. More...

dbus_bool_t _dbus_string_align_length (DBusString *str, int alignment)
 Align the length of a string to a specific alignment (typically 4 or 8) by appending nul bytes to the string. More...

dbus_bool_t _dbus_string_append (DBusString *str, const char *buffer)
 Appends a nul-terminated C-style string to a DBusString. More...

dbus_bool_t _dbus_string_append_4_aligned (DBusString *str, const unsigned char octets[4])
 Appends 4 bytes aligned on a 4 byte boundary with any alignment padding initialized to 0. More...

dbus_bool_t _dbus_string_append_8_aligned (DBusString *str, const unsigned char octets[8])
 Appends 8 bytes aligned on an 8 byte boundary with any alignment padding initialized to 0. More...

dbus_bool_t _dbus_string_append_printf_valist (DBusString *str, const char *format, va_list args)
 Appends a printf-style formatted string to the DBusString. More...

dbus_bool_t _dbus_string_append_printf (DBusString *str, const char *format,...)
 Appends a printf-style formatted string to the DBusString. More...

dbus_bool_t _dbus_string_append_len (DBusString *str, const char *buffer, int len)
 Appends block of bytes with the given length to a DBusString. More...

dbus_bool_t _dbus_string_append_byte (DBusString *str, unsigned char byte)
 Appends a single byte to the string, returning FALSE if not enough memory. More...

dbus_bool_t _dbus_string_append_unichar (DBusString *str, dbus_unichar_t ch)
 Appends a single Unicode character, encoding the character in UTF-8 format. More...

void _dbus_string_delete (DBusString *str, int start, int len)
 Deletes a segment of a DBusString with length len starting at start. More...

dbus_bool_t _dbus_string_move (DBusString *source, int start, DBusString *dest, int insert_at)
 Moves the end of one string into another string. More...

dbus_bool_t _dbus_string_copy (const DBusString *source, int start, DBusString *dest, int insert_at)
 Like _dbus_string_move(), but does not delete the section of the source string that's copied to the dest string. More...

dbus_bool_t _dbus_string_move_len (DBusString *source, int start, int len, DBusString *dest, int insert_at)
 Like _dbus_string_move(), but can move a segment from the middle of the source string. More...

dbus_bool_t _dbus_string_copy_len (const DBusString *source, int start, int len, DBusString *dest, int insert_at)
 Like _dbus_string_copy(), but can copy a segment from the middle of the source string. More...

dbus_bool_t _dbus_string_replace_len (const DBusString *source, int start, int len, DBusString *dest, int replace_at, int replace_len)
 Replaces a segment of dest string with a segment of source string. More...

void _dbus_string_get_unichar (const DBusString *str, int start, dbus_unichar_t *ch_return, int *end_return)
 Gets a unicode character from a UTF-8 string. More...

dbus_bool_t _dbus_string_find (const DBusString *str, int start, const char *substr, int *found)
 Finds the given substring in the string, returning TRUE and filling in the byte index where the substring was found, if it was found. More...

dbus_bool_t _dbus_string_find_to (const DBusString *str, int start, int end, const char *substr, int *found)
 Finds the given substring in the string, up to a certain position, returning TRUE and filling in the byte index where the substring was found, if it was found. More...

dbus_bool_t _dbus_string_find_byte_backward (const DBusString *str, int start, unsigned char byte, int *found)
 Find the given byte scanning backward from the given start. More...

dbus_bool_t _dbus_string_find_blank (const DBusString *str, int start, int *found)
 Finds a blank (space or tab) in the string. More...

void _dbus_string_skip_blank (const DBusString *str, int start, int *end)
 Skips blanks from start, storing the first non-blank in *end (blank is space or tab). More...

void _dbus_string_skip_white (const DBusString *str, int start, int *end)
 Skips whitespace from start, storing the first non-whitespace in *end. More...

dbus_bool_t _dbus_string_pop_line (DBusString *source, DBusString *dest)
 Assigns a newline-terminated or \r\n-terminated line from the front of the string to the given dest string. More...

void _dbus_string_delete_first_word (DBusString *str)
 Deletes up to and including the first blank space in the string. More...

void _dbus_string_delete_leading_blanks (DBusString *str)
 Deletes any leading blanks in the string. More...

dbus_bool_t _dbus_string_equal (const DBusString *a, const DBusString *b)
 Tests two DBusString for equality. More...

dbus_bool_t _dbus_string_equal_len (const DBusString *a, const DBusString *b, int len)
 Tests two DBusString for equality up to the given length. More...

dbus_bool_t _dbus_string_equal_c_str (const DBusString *a, const char *c_str)
 Checks whether a string is equal to a C string. More...

dbus_bool_t _dbus_string_starts_with_c_str (const DBusString *a, const char *c_str)
 Checks whether a string starts with the given C string. More...

dbus_bool_t _dbus_string_ends_with_c_str (const DBusString *a, const char *c_str)
 Returns whether a string ends with the given suffix. More...

dbus_bool_t _dbus_string_hex_encode (const DBusString *source, int start, DBusString *dest, int insert_at)
 Encodes a string in hex, the way MD5 and SHA-1 are usually encoded. More...

dbus_bool_t _dbus_string_hex_decode (const DBusString *source, int start, int *end_return, DBusString *dest, int insert_at)
 Decodes a string from hex encoding. More...

dbus_bool_t _dbus_string_validate_ascii (const DBusString *str, int start, int len)
 Checks that the given range of the string is valid ASCII with no nul bytes. More...

dbus_bool_t _dbus_string_validate_utf8 (const DBusString *str, int start, int len)
 Checks that the given range of the string is valid UTF-8. More...

dbus_bool_t _dbus_string_validate_nul (const DBusString *str, int start, int len)
 Checks that the given range of the string is all nul bytes. More...

dbus_bool_t _dbus_string_validate_path (const DBusString *str, int start, int len)
 Checks that the given range of the string is a valid object path name in the D-BUS protocol. More...

dbus_bool_t _dbus_string_validate_interface (const DBusString *str, int start, int len)
 Checks that the given range of the string is a valid interface name in the D-BUS protocol. More...

dbus_bool_t _dbus_string_validate_member (const DBusString *str, int start, int len)
 Checks that the given range of the string is a valid member name in the D-BUS protocol. More...

dbus_bool_t _dbus_string_validate_error_name (const DBusString *str, int start, int len)
 Checks that the given range of the string is a valid error name in the D-BUS protocol. More...

dbus_bool_t _dbus_string_validate_service (const DBusString *str, int start, int len)
 Checks that the given range of the string is a valid service name in the D-BUS protocol. More...

void _dbus_string_zero (DBusString *str)
 Clears all allocated bytes in the string to zero. More...

dbus_bool_t _dbus_string_append_int (DBusString *str, long value)
 Appends an integer to a DBusString. More...

dbus_bool_t _dbus_string_append_uint (DBusString *str, unsigned long value)
 Appends an unsigned integer to a DBusString. More...

dbus_bool_t _dbus_string_append_double (DBusString *str, double value)
 Appends a double to a DBusString. More...

dbus_bool_t _dbus_string_parse_int (const DBusString *str, int start, long *value_return, int *end_return)
 Parses an integer contained in a DBusString. More...

dbus_bool_t _dbus_string_parse_uint (const DBusString *str, int start, unsigned long *value_return, int *end_return)
 Parses an unsigned integer contained in a DBusString. More...

dbus_bool_t _dbus_string_parse_double (const DBusString *str, int start, double *value, int *end_return)
 Parses a floating point number contained in a DBusString. More...


Detailed Description

DBusString data structure.

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"


Define Documentation

#define DBUS_STRING_COPY_PREAMBLE source,
start,
dest,
insert_at   
 

Value:

DBusRealString *real_source = (DBusRealString*) source;               \
  DBusRealString *real_dest = (DBusRealString*) dest;                   \
  _dbus_assert ((source) != (dest));                                    \
  DBUS_GENERIC_STRING_PREAMBLE (real_source);                           \
  DBUS_GENERIC_STRING_PREAMBLE (real_dest);                             \
  _dbus_assert (!real_dest->constant);                                  \
  _dbus_assert (!real_dest->locked);                                    \
  _dbus_assert ((start) >= 0);                                          \
  _dbus_assert ((start) <= real_source->len);                           \
  _dbus_assert ((insert_at) >= 0);                                      \
  _dbus_assert ((insert_at) <= real_dest->len)
Checks assertions for two strings we're copying a segment between, and declares real_source/real_dest variables.

Parameters:
source  the source string
start  the starting offset
dest  the dest string
insert_at  where the copied segment is inserted

Definition at line 1243 of file dbus-string.c.

#define UNICODE_VALID Char   
 

Value:

((Char) < 0x110000 &&                     \
     (((Char) & 0xFFFFF800) != 0xD800) &&     \
     ((Char) < 0xFDD0 || (Char) > 0xFDEF) &&  \
     ((Char) & 0xFFFF) != 0xFFFF)
Check whether a unicode char is in a valid range.

Parameters:
Char  the character

Definition at line 1529 of file dbus-string.c.

#define UTF8_COMPUTE Char,
Mask,
Len   
 

computes length and mask of a unicode character.

Parameters:
Char  the char
Mask  the mask variable to assign to
Len  the length variable to assign to

Definition at line 1457 of file dbus-string.c.

#define UTF8_GET Result,
Chars,
Count,
Mask,
Len   
 

Value:

(Result) = (Chars)[0] & (Mask);                                       \
  for ((Count) = 1; (Count) < (Len); ++(Count))                               \
    {                                                                         \
      if (((Chars)[(Count)] & 0xc0) != 0x80)                                  \
        {                                                                     \
          (Result) = -1;                                                      \
          break;                                                              \
        }                                                                     \
      (Result) <<= 6;                                                         \
      (Result) |= ((Chars)[(Count)] & 0x3f);                                  \
    }
Gets a UTF-8 value.

Parameters:
Result  variable for extracted unicode char.
Chars  the bytes to decode
Count  counter variable
Mask  mask for this char
Len  length for this char in bytes

Definition at line 1511 of file dbus-string.c.

#define UTF8_LENGTH Char   
 

Value:

((Char) < 0x80 ? 1 :                 \
   ((Char) < 0x800 ? 2 :               \
    ((Char) < 0x10000 ? 3 :            \
     ((Char) < 0x200000 ? 4 :          \
      ((Char) < 0x4000000 ? 5 : 6)))))
computes length of a unicode character in UTF-8.

Parameters:
Char  the char

Definition at line 1495 of file dbus-string.c.

#define VALID_INITIAL_NAME_CHARACTER  
 

Value:

( ((c) >= 'A' && (c) <= 'Z') ||               \
    ((c) >= 'a' && (c) <= 'z') ||               \
    ((c) == '_') )
Determine wether the given charater is valid as the first charater in a name.

Definition at line 2558 of file dbus-string.c.

#define VALID_NAME_CHARACTER  
 

Value:

( ((c) >= '0' && (c) <= '9') ||               \
    ((c) >= 'A' && (c) <= 'Z') ||               \
    ((c) >= 'a' && (c) <= 'z') ||               \
    ((c) == '_') )
Determine wether the given charater is valid as a second or later character in a nam.

Definition at line 2567 of file dbus-string.c.


Function Documentation

dbus_bool_t _dbus_string_align_length DBusString   str,
int    alignment
 

Align the length of a string to a specific alignment (typically 4 or 8) by appending nul bytes to the string.

Parameters:
str  a string
alignment  the alignment
Returns:
FALSE if no memory

Definition at line 887 of file dbus-string.c.

dbus_bool_t _dbus_string_append DBusString   str,
const char *    buffer
 

Appends a nul-terminated C-style string to a DBusString.

Parameters:
str  the DBusString
buffer  the nul-terminated characters to append
Returns:
FALSE if not enough memory.

Definition at line 919 of file dbus-string.c.

References DBusRealString::max_length.

dbus_bool_t _dbus_string_append_4_aligned DBusString   str,
const unsigned char    octets[4]
 

Appends 4 bytes aligned on a 4 byte boundary with any alignment padding initialized to 0.

Parameters:
str  the DBusString
octets  4 bytes to append
Returns:
FALSE if not enough memory.

Definition at line 943 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_append_8_aligned DBusString   str,
const unsigned char    octets[8]
 

Appends 8 bytes aligned on an 8 byte boundary with any alignment padding initialized to 0.

Parameters:
str  the DBusString
octets  4 bytes to append
Returns:
FALSE if not enough memory.

Definition at line 967 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_append_byte DBusString   str,
unsigned char    byte
 

Appends a single byte to the string, returning FALSE if not enough memory.

Parameters:
str  the string
byte  the byte to append
Returns:
TRUE on success

Definition at line 1094 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_append_double DBusString   str,
double    value
 

Appends a double to a DBusString.

Parameters:
str  the string
value  the floating point value
Returns:
FALSE if not enough memory or other failure.

Definition at line 1059 of file dbus-sysdeps.c.

dbus_bool_t _dbus_string_append_int DBusString   str,
long    value
 

Appends an integer to a DBusString.

Parameters:
str  the string
value  the integer value
Returns:
FALSE if not enough memory or other failure.

Definition at line 983 of file dbus-sysdeps.c.

dbus_bool_t _dbus_string_append_len DBusString   str,
const char *    buffer,
int    len
 

Appends block of bytes with the given length to a DBusString.

Parameters:
str  the DBusString
buffer  the bytes to append
len  the number of bytes to append
Returns:
FALSE if not enough memory.

Definition at line 1074 of file dbus-string.c.

dbus_bool_t _dbus_string_append_printf DBusString   str,
const char *    format,
...   
 

Appends a printf-style formatted string to the DBusString.

Parameters:
str  the string
format  printf format
Returns:
FALSE if no memory

Definition at line 1051 of file dbus-string.c.

dbus_bool_t _dbus_string_append_printf_valist DBusString   str,
const char *    format,
va_list    args
 

Appends a printf-style formatted string to the DBusString.

Parameters:
str  the string
format  printf format
args  variable argument list
Returns:
FALSE if no memory

Definition at line 1012 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_append_uint DBusString   str,
unsigned long    value
 

Appends an unsigned integer to a DBusString.

Parameters:
str  the string
value  the integer value
Returns:
FALSE if not enough memory or other failure.

Definition at line 1021 of file dbus-sysdeps.c.

dbus_bool_t _dbus_string_append_unichar DBusString   str,
dbus_unichar_t    ch
 

Appends a single Unicode character, encoding the character in UTF-8 format.

Parameters:
str  the string
ch  the Unicode character

Definition at line 1115 of file dbus-string.c.

References DBusRealString::len, DBusRealString::max_length, and DBusRealString::str.

dbus_bool_t _dbus_string_copy const DBusString   source,
int    start,
DBusString   dest,
int    insert_at
 

Like _dbus_string_move(), but does not delete the section of the source string that's copied to the dest string.

Parameters:
source  the source string
start  where to start copying the source string
dest  the destination string
insert_at  where to place the copied part of source string
Returns:
FALSE if not enough memory

Definition at line 1291 of file dbus-string.c.

dbus_bool_t _dbus_string_copy_data const DBusString   str,
char **    data_return
 

Copies the data from the string into a char*.

Parameters:
str  the string
data_return  place to return the data
Returns:
TRUE on success, FALSE on no memory

Definition at line 699 of file dbus-string.c.

dbus_bool_t _dbus_string_copy_data_len const DBusString   str,
char **    data_return,
int    start,
int    len
 

Copies a segment of the string into a char*.

Parameters:
str  the string
data_return  place to return the data
start  start index
len  length to copy
Returns:
FALSE if no memory

Definition at line 724 of file dbus-string.c.

dbus_bool_t _dbus_string_copy_len const DBusString   source,
int    start,
int    len,
DBusString   dest,
int    insert_at
 

Like _dbus_string_copy(), but can copy a segment from the middle of the source string.

Parameters:
source  the source string
start  where to start copying the source string
len  length of segment to copy
dest  the destination string
insert_at  where to place the copied segment of source string
Returns:
FALSE if not enough memory

Definition at line 1386 of file dbus-string.c.

void _dbus_string_delete DBusString   str,
int    start,
int    len
 

Deletes a segment of a DBusString with length len starting at start.

(Hint: to clear an entire string, setting length to 0 with _dbus_string_set_length() is easier.)

Parameters:
str  the DBusString
start  where to start deleting
len  the number of bytes to delete

Definition at line 1201 of file dbus-string.c.

void _dbus_string_delete_first_word DBusString   str
 

Deletes up to and including the first blank space in the string.

Parameters:
str  the string

Definition at line 1904 of file dbus-string.c.

void _dbus_string_delete_leading_blanks DBusString   str
 

Deletes any leading blanks in the string.

Parameters:
str  the string

Definition at line 1920 of file dbus-string.c.

dbus_bool_t _dbus_string_ends_with_c_str const DBusString   a,
const char *    c_str
 

Returns whether a string ends with the given suffix.

Todo:
memcmp might make this faster.
Parameters:
a  the string
c_str  the C-style string
Returns:
TRUE if the string ends with the suffix

Definition at line 2095 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_equal const DBusString   a,
const DBusString   b
 

Tests two DBusString for equality.

Todo:
memcmp is probably faster
Parameters:
a  first string
b  second string
Returns:
TRUE if equal

Definition at line 1940 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_equal_c_str const DBusString   a,
const char *    c_str
 

Checks whether a string is equal to a C string.

Parameters:
a  the string
c_str  the C string
Returns:
TRUE if equal

Definition at line 2021 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_equal_len const DBusString   a,
const DBusString   b,
int    len
 

Tests two DBusString for equality up to the given length.

Todo:
write a unit test

memcmp is probably faster

Parameters:
a  first string
b  second string
len  the lengh
Returns:
TRUE if equal for the given number of bytes

Definition at line 1982 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_find const DBusString   str,
int    start,
const char *    substr,
int *    found
 

Finds the given substring in the string, returning TRUE and filling in the byte index where the substring was found, if it was found.

Returns FALSE if the substring wasn't found. Sets *start to the length of the string if the substring is not found.

Parameters:
str  the string
start  where to start looking
substr  the substring
found  return location for where it was found, or NULL
Returns:
TRUE if found

Definition at line 1597 of file dbus-string.c.

dbus_bool_t _dbus_string_find_blank const DBusString   str,
int    start,
int *    found
 

Finds a blank (space or tab) in the string.

Returns TRUE if found, FALSE otherwise. If a blank is not found sets *found to the length of the string.

Parameters:
str  the string
start  byte index to start looking
found  place to store the location of the first blank
Returns:
TRUE if a blank was found

Definition at line 1729 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_find_byte_backward const DBusString   str,
int    start,
unsigned char    byte,
int *    found
 

Find the given byte scanning backward from the given start.

Sets *found to -1 if the byte is not found.

Parameters:
str  the string
start  the place to start scanning (will not find the byte at this point)
byte  the byte to find
found  return location for where it was found
Returns:
TRUE if found

Definition at line 1692 of file dbus-string.c.

References DBusRealString::str.

dbus_bool_t _dbus_string_find_to const DBusString   str,
int    start,
int    end,
const char *    substr,
int *    found
 

Finds the given substring in the string, up to a certain position, returning TRUE and filling in the byte index where the substring was found, if it was found.

Returns FALSE if the substring wasn't found. Sets *start to the length of the string if the substring is not found.

Parameters:
str  the string
start  where to start looking
end  where to stop looking
substr  the substring
found  return location for where it was found, or NULL
Returns:
TRUE if found

Definition at line 1624 of file dbus-string.c.

References DBusRealString::str.

void _dbus_string_free DBusString   str
 

Frees a string created by _dbus_string_init().

Parameters:
str  memory where the string is stored.

Definition at line 312 of file dbus-string.c.

References DBusRealString::align_offset, DBusRealString::constant, DBusRealString::invalid, and DBusRealString::str.

unsigned char _dbus_string_get_byte const DBusString   str,
int    start
 

Gets the byte at the given position.

It is allowed to ask for the nul byte at the end of the string.

Parameters:
str  the string
start  the position
Returns:
the byte at that position

Definition at line 558 of file dbus-string.c.

const char* _dbus_string_get_const_data const DBusString   str
 

Gets the raw character buffer from a const string.

Parameters:
str  the string
Returns:
the string data

Definition at line 473 of file dbus-string.c.

const char* _dbus_string_get_const_data_len const DBusString   str,
int    start,
int    len
 

const version of _dbus_string_get_data_len().

Parameters:
str  the string
start  byte offset to return
len  length of segment to return
Returns:
the string data

Definition at line 516 of file dbus-string.c.

char* _dbus_string_get_data DBusString   str
 

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.

Parameters:
str  the string
Returns:
the data

Definition at line 459 of file dbus-string.c.

char* _dbus_string_get_data_len DBusString   str,
int    start,
int    len
 

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.

Parameters:
str  the string
start  byte offset to return
len  length of segment to return
Returns:
the string data

Definition at line 494 of file dbus-string.c.

int _dbus_string_get_length const DBusString   str
 

Gets the length of a string (not including nul termination).

Returns:
the length.

Definition at line 765 of file dbus-string.c.

void _dbus_string_get_unichar const DBusString   str,
int    start,
dbus_unichar_t *    ch_return,
int *    end_return
 

Gets a unicode character from a UTF-8 string.

Does no validation; you must verify that the string is valid UTF-8 in advance and must pass in the start of a character.

Parameters:
str  the string
start  the start of the UTF-8 character.
ch_return  location to return the character
end_return  location to return the byte index of next character

Definition at line 1546 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_hex_decode const DBusString   source,
int    start,
int *    end_return,
DBusString   dest,
int    insert_at
 

Decodes a string from hex encoding.

Parameters:
source  the string to decode
start  byte index to start decode
end_return  return location of the end of the hex data, or NULL
dest  string where decoded data should be placed
insert_at  where to place decoded data
Returns:
TRUE if decoding was successful, FALSE if no memory.

Definition at line 2198 of file dbus-string.c.

dbus_bool_t _dbus_string_hex_encode const DBusString   source,
int    start,
DBusString   dest,
int    insert_at
 

Encodes a string in hex, the way MD5 and SHA-1 are usually encoded.

(Each byte is two hex digits.)

Parameters:
source  the string to encode
start  byte index to start encoding
dest  string where encoded data should be placed
insert_at  where to place encoded data
Returns:
TRUE if encoding was successful, FALSE if no memory etc.

Definition at line 2139 of file dbus-string.c.

dbus_bool_t _dbus_string_init DBusString   str
 

Initializes a string.

The string starts life with zero length. The string must eventually be freed with _dbus_string_free().

Parameters:
str  memory to hold the string
Returns:
TRUE on success, FALSE if no memory

Definition at line 229 of file dbus-string.c.

void _dbus_string_init_const DBusString   str,
const char *    value
 

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.

Parameters:
str  memory to use for the string
value  a string to be stored in str (not copied!!!)

Definition at line 261 of file dbus-string.c.

void _dbus_string_init_const_len DBusString   str,
const char *    value,
int    len
 

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.

Parameters:
str  memory to use for the string
value  a string to be stored in str (not copied!!!)
len  the length to use

Definition at line 281 of file dbus-string.c.

References DBusRealString::allocated, DBusRealString::constant, DBusRealString::invalid, DBusRealString::len, DBusRealString::max_length, and DBusRealString::str.

dbus_bool_t _dbus_string_init_preallocated DBusString   str,
int    allocate_size
 

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().

Parameters:
str  memory to hold the string
allocate_size  amount to preallocate
Returns:
TRUE on success, FALSE if no memory

Definition at line 185 of file dbus-string.c.

References DBusRealString::align_offset, DBusRealString::allocated, DBusRealString::constant, DBusRealString::invalid, DBusRealString::len, DBusRealString::locked, DBusRealString::max_length, and DBusRealString::str.

dbus_bool_t _dbus_string_insert_bytes DBusString   str,
int    i,
int    n_bytes,
unsigned char    byte
 

Inserts a number of bytes of a given value at the given position.

Parameters:
str  the string
i  the position
n_bytes  number of bytes
byte  the value to insert
Returns:
TRUE on success

Definition at line 579 of file dbus-string.c.

dbus_bool_t _dbus_string_lengthen DBusString   str,
int    additional_length
 

Makes a string longer by the given number of bytes.

Checks whether adding additional_length to the current length would overflow an integer, and checks for exceeding a string's max length. The new bytes are not initialized, other than nul-terminating the end of the string. The uninitialized bytes may contain nul bytes or other junk.

Parameters:
str  a string
additional_length  length to add to the string.
Returns:
TRUE on success.

Definition at line 785 of file dbus-string.c.

void _dbus_string_lock DBusString   str
 

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.

Parameters:
str  the string to lock.

Definition at line 338 of file dbus-string.c.

dbus_bool_t _dbus_string_move DBusString   source,
int    start,
DBusString   dest,
int    insert_at
 

Moves the end of one string into another string.

Both strings must be initialized, valid strings.

Parameters:
source  the source string
start  where to chop off the source string
dest  the destination string
insert_at  where to move the chopped-off part of source string
Returns:
FALSE if not enough memory

Definition at line 1267 of file dbus-string.c.

References DBusRealString::len.

dbus_bool_t _dbus_string_move_len DBusString   source,
int    start,
int    len,
DBusString   dest,
int    insert_at
 

Like _dbus_string_move(), but can move a segment from the middle of the source string.

Todo:
this doesn't do anything with max_length field. we should probably just kill the max_length field though.
Parameters:
source  the source string
start  first byte of source string to move
len  length of segment to move
dest  the destination string
insert_at  where to move the bytes from the source string
Returns:
FALSE if not enough memory

Definition at line 1319 of file dbus-string.c.

dbus_bool_t _dbus_string_parse_double const DBusString   str,
int    start,
double *    value_return,
int *    end_return
 

Parses a floating point number contained in a DBusString.

Either return parameter may be NULL if you aren't interested in it. The integer is parsed and stored in value_return. Return parameters are not initialized if the function returns FALSE.

Parameters:
str  the string
start  the byte index of the start of the float
value_return  return location of the float value or NULL
end_return  return location of the end of the float, or NULL
Returns:
TRUE on success

Definition at line 1338 of file dbus-sysdeps.c.

dbus_bool_t _dbus_string_parse_int const DBusString   str,
int    start,
long *    value_return,
int *    end_return
 

Parses an integer contained in a DBusString.

Either return parameter may be NULL if you aren't interested in it. The integer is parsed and stored in value_return. Return parameters are not initialized if the function returns FALSE.

Parameters:
str  the string
start  the byte index of the start of the integer
value_return  return location of the integer value or NULL
end_return  return location of the end of the integer, or NULL
Returns:
TRUE on success

Definition at line 1101 of file dbus-sysdeps.c.

dbus_bool_t _dbus_string_parse_uint const DBusString   str,
int    start,
unsigned long *    value_return,
int *    end_return
 

Parses an unsigned integer contained in a DBusString.

Either return parameter may be NULL if you aren't interested in it. The integer is parsed and stored in value_return. Return parameters are not initialized if the function returns FALSE.

Parameters:
str  the string
start  the byte index of the start of the integer
value_return  return location of the integer value or NULL
end_return  return location of the end of the integer, or NULL
Returns:
TRUE on success

Definition at line 1142 of file dbus-sysdeps.c.

dbus_bool_t _dbus_string_pop_line DBusString   source,
DBusString   dest
 

Assigns a newline-terminated or \r\n-terminated line from the front of the string to the given dest string.

The dest string's previous contents are deleted. If the source string contains no newline, moves the entire source string to the dest string.

Todo:
owen correctly notes that this is a stupid function (it was written purely for test code, e.g. dbus-message-builder.c). Probably should be enforced as test code only with ifdef DBUS_BUILD_TESTS
Parameters:
source  the source string
dest  the destination string (contents are replaced)
Returns:
FALSE if no memory, or source has length 0

Definition at line 1846 of file dbus-string.c.

dbus_bool_t _dbus_string_replace_len const DBusString   source,
int    start,
int    len,
DBusString   dest,
int    replace_at,
int    replace_len
 

Replaces a segment of dest string with a segment of source string.

Todo:
optimize the case where the two lengths are the same, and avoid memmoving the data in the trailing part of the string twice.

avoid inserting the source into dest, then deleting the replaced chunk of dest (which creates a potentially large intermediate string). Instead, extend the replaced chunk of dest with padding to the same size as the source chunk, then copy in the source bytes.

Parameters:
source  the source string
start  where to start copying the source string
len  length of segment to copy
dest  the destination string
replace_at  start of segment of dest string to replace
replace_len  length of segment of dest string to replace
Returns:
FALSE if not enough memory

Definition at line 1424 of file dbus-string.c.

void _dbus_string_set_byte DBusString   str,
int    i,
unsigned char    byte
 

Sets the value of the byte at the given position.

Parameters:
str  the string
i  the position
byte  the new value

Definition at line 537 of file dbus-string.c.

dbus_bool_t _dbus_string_set_length DBusString   str,
int    length
 

Sets the length of a string.

Can be used to truncate or lengthen the string. If the string is lengthened, the function may fail and return FALSE. Newly-added bytes are not initialized, as with _dbus_string_lengthen().

Parameters:
str  a string
length  new length of the string.
Returns:
FALSE on failure.

Definition at line 827 of file dbus-string.c.

void _dbus_string_shorten DBusString   str,
int    length_to_remove
 

Makes a string shorter by the given number of bytes.

Parameters:
str  a string
length_to_remove  length to remove from the string.

Definition at line 805 of file dbus-string.c.

void _dbus_string_skip_blank const DBusString   str,
int    start,
int *    end
 

Skips blanks from start, storing the first non-blank in *end (blank is space or tab).

Parameters:
str  the string
start  where to start
end  where to store the first non-blank byte index

Definition at line 1767 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

void _dbus_string_skip_white const DBusString   str,
int    start,
int *    end
 

Skips whitespace from start, storing the first non-whitespace in *end.

(whitespace is space, tab, newline, CR).

Parameters:
str  the string
start  where to start
end  where to store the first non-whitespace byte index

Definition at line 1802 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_starts_with_c_str const DBusString   a,
const char *    c_str
 

Checks whether a string starts with the given C string.

Parameters:
a  the string
c_str  the C string
Returns:
TRUE if string starts with it

Definition at line 2057 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_steal_data DBusString   str,
char **    data_return
 

Like _dbus_string_get_data(), but removes the gotten data from the original string.

The caller must free the data returned. This function may fail due to lack of memory, and return FALSE.

Parameters:
str  the string
data_return  location to return the buffer
Returns:
TRUE on success

Definition at line 611 of file dbus-string.c.

dbus_bool_t _dbus_string_steal_data_len DBusString   str,
char **    data_return,
int    start,
int    len
 

Like _dbus_string_get_data_len(), but removes the gotten data from the original string.

The caller must free the data returned. This function may fail due to lack of memory, and return FALSE. The returned string is nul-terminated and has length len.

Todo:
this function is broken because on failure it may corrupt the source string.
Parameters:
str  the string
data_return  location to return the buffer
start  the start of segment to steal
len  the length of segment to steal
Returns:
TRUE on success

Definition at line 655 of file dbus-string.c.

dbus_bool_t _dbus_string_validate_ascii const DBusString   str,
int    start,
int    len
 

Checks that the given range of the string is valid ASCII with no nul bytes.

If the given range is not entirely contained in the string, returns FALSE.

Todo:
this is inconsistent with most of DBusString in that it allows a start,len range that isn't in the string.
Parameters:
str  the string
start  first byte index to check
len  number of bytes to check
Returns:
TRUE if the byte range exists and is all valid ASCII

Definition at line 2339 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_validate_error_name const DBusString   str,
int    start,
int    len
 

Checks that the given range of the string is a valid error name in the D-BUS protocol.

This includes a length restriction, etc., see the specification.

Todo:
this is inconsistent with most of DBusString in that it allows a start,len range that isn't in the string.
Parameters:
str  the string
start  first byte index to check
len  number of bytes to check
Returns:
TRUE if the byte range exists and is a valid name

Definition at line 2726 of file dbus-string.c.

dbus_bool_t _dbus_string_validate_interface const DBusString   str,
int    start,
int    len
 

Checks that the given range of the string is a valid interface name in the D-BUS protocol.

This includes a length restriction and an ASCII subset, see the specification.

Todo:
this is inconsistent with most of DBusString in that it allows a start,len range that isn't in the string.
Parameters:
str  the string
start  first byte index to check
len  number of bytes to check
Returns:
TRUE if the byte range exists and is a valid name

Definition at line 2587 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_validate_member const DBusString   str,
int    start,
int    len
 

Checks that the given range of the string is a valid member name in the D-BUS protocol.

This includes a length restriction, etc., see the specification.

Todo:
this is inconsistent with most of DBusString in that it allows a start,len range that isn't in the string.
Parameters:
str  the string
start  first byte index to check
len  number of bytes to check
Returns:
TRUE if the byte range exists and is a valid name

Definition at line 2664 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_validate_nul const DBusString   str,
int    start,
int    len
 

Checks that the given range of the string is all nul bytes.

If the given range is not entirely contained in the string, returns FALSE.

Todo:
this is inconsistent with most of DBusString in that it allows a start,len range that isn't in the string.
Parameters:
str  the string
start  first byte index to check
len  number of bytes to check
Returns:
TRUE if the byte range exists and is all nul bytes

Definition at line 2460 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_validate_path const DBusString   str,
int    start,
int    len
 

Checks that the given range of the string is a valid object path name in the D-BUS protocol.

This includes a length restriction, etc., see the specification. It does not validate UTF-8, that has to be done separately for now.

Todo:
this is inconsistent with most of DBusString in that it allows a start,len range that isn't in the string.

change spec to disallow more things, such as spaces in the path name

Parameters:
str  the string
start  first byte index to check
len  number of bytes to check
Returns:
TRUE if the byte range exists and is a valid name

Definition at line 2504 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

dbus_bool_t _dbus_string_validate_service const DBusString   str,
int    start,
int    len
 

Checks that the given range of the string is a valid service name in the D-BUS protocol.

This includes a length restriction, etc., see the specification.

Todo:
this is inconsistent with most of DBusString in that it allows a start,len range that isn't in the string.
Parameters:
str  the string
start  first byte index to check
len  number of bytes to check
Returns:
TRUE if the byte range exists and is a valid name

Definition at line 2797 of file dbus-string.c.

dbus_bool_t _dbus_string_validate_utf8 const DBusString   str,
int    start,
int    len
 

Checks that the given range of the string is valid UTF-8.

If the given range is not entirely contained in the string, returns FALSE. If the string contains any nul bytes in the given range, returns FALSE. If the start and start+len are not on character boundaries, returns FALSE.

Todo:
this is inconsistent with most of DBusString in that it allows a start,len range that isn't in the string.
Parameters:
str  the string
start  first byte index to check
len  number of bytes to check
Returns:
TRUE if the byte range exists and is all valid UTF-8

Definition at line 2383 of file dbus-string.c.

References DBusRealString::len, and DBusRealString::str.

void _dbus_string_zero DBusString   str
 

Clears all allocated bytes in the string to zero.

Parameters:
str  the string

Definition at line 2815 of file dbus-string.c.

References DBusRealString::align_offset, DBusRealString::allocated, and DBusRealString::str.


Generated on Wed Jun 9 05:01:28 2004 for D-BUS by doxygen1.2.15