1/* Copyright (C) 2007-2008 The Android Open Source Project
2**
3** This software is licensed under the terms of the GNU General Public
4** License version 2, as published by the Free Software Foundation, and
5** may be copied, distributed, and modified under those terms.
6**
7** This program is distributed in the hope that it will be useful,
8** but WITHOUT ANY WARRANTY; without even the implied warranty of
9** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10** GNU General Public License for more details.
11*/
12
13#ifndef _ANDROID_UTILS_BUFPRINT_H
14#define _ANDROID_UTILS_BUFPRINT_H
15
16#include <stdarg.h>
17
18/** FORMATTED BUFFER PRINTING
19 **
20 **  bufprint() allows your to easily and safely append formatted string
21 **  content to a given bounded character buffer, in a way that is easier
22 **  to use than raw snprintf()
23 **
24 **  'buffer'  is the start position in the buffer,
25 **  'buffend' is the end of the buffer, the function assumes (buffer <= buffend)
26 **  'format'  is a standard printf-style format string, followed by any number
27 **            of formatting arguments
28 **
29 **  the function returns the next position in the buffer if everything fits
30 **  in it. in case of overflow or formatting error, it will always return "buffend"
31 **
32 **  this allows you to chain several calls to bufprint() and only check for
33 **  overflow at the end, for exemple:
34 **
35 **     char   buffer[1024];
36 **     char*  p   = buffer;
37 **     char*  end = p + sizeof(buffer);
38 **
39 **     p = bufprint(p, end, "%s/%s", first, second);
40 **     p = bufprint(p, end, "/%s", third);
41 **     if (p >= end) ---> overflow
42 **
43 **  as a convenience, the appended string is zero-terminated if there is no overflow.
44 **  (this means that even if p >= end, the content of "buffer" is zero-terminated)
45 **
46 **  vbufprint() is a variant that accepts a va_list argument
47 **/
48
49extern char*   vbufprint(char*  buffer, char*  buffend, const char*  fmt, va_list  args );
50extern char*   bufprint (char*  buffer, char*  buffend, const char*  fmt, ... );
51
52/** USEFUL DIRECTORY SUPPORT
53 **
54 **  bufprint_add_dir() appends the application's directory to a given bounded buffer
55 **
56 **  bufprint_config_path() appends the applications' user-specific configuration directory
57 **  to a bounded buffer. on Unix this is usually ~/.android, and something a bit more
58 **  complex on Windows
59 **
60 **  bufprint_config_file() appends the name of a file or directory relative to the
61 **  user-specific configuration directory to a bounded buffer. this really is equivalent
62 **  to concat-ing the config path + path separator + 'suffix'
63 **
64 **  bufprint_temp_dir() appends the temporary directory's path to a given bounded buffer
65 **
66 **  bufprint_temp_file() appens the name of a file or directory relative to the
67 **  temporary directory. equivalent to concat-ing the temp path + path separator + 'suffix'
68 **/
69
70extern char*  bufprint_app_dir    (char*  buffer, char*  buffend);
71extern char*  bufprint_config_path(char*  buffer, char*  buffend);
72extern char*  bufprint_config_file(char*  buffer, char*  buffend, const char*  suffix);
73extern char*  bufprint_temp_dir   (char*  buffer, char*  buffend);
74extern char*  bufprint_temp_file  (char*  buffer, char*  buffend, const char*  suffix);
75
76#endif /* _ANDROID_UTILS_BUFPRINT_H */
77