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#include "android/utils/compiler.h"
19
20ANDROID_BEGIN_HEADER
21
22/** FORMATTED BUFFER PRINTING
23 **
24 **  bufprint() allows your to easily and safely append formatted string
25 **  content to a given bounded character buffer, in a way that is easier
26 **  to use than raw snprintf()
27 **
28 **  'buffer'  is the start position in the buffer,
29 **  'buffend' is the end of the buffer, the function assumes (buffer <= buffend)
30 **  'format'  is a standard printf-style format string, followed by any number
31 **            of formatting arguments
32 **
33 **  the function returns the next position in the buffer if everything fits
34 **  in it. in case of overflow or formatting error, it will always return "buffend"
35 **
36 **  this allows you to chain several calls to bufprint() and only check for
37 **  overflow at the end, for exemple:
38 **
39 **     char   buffer[1024];
40 **     char*  p   = buffer;
41 **     char*  end = p + sizeof(buffer);
42 **
43 **     p = bufprint(p, end, "%s/%s", first, second);
44 **     p = bufprint(p, end, "/%s", third);
45 **     if (p >= end) ---> overflow
46 **
47 **  as a convenience, the appended string is zero-terminated if there is no overflow.
48 **  (this means that even if p >= end, the content of "buffer" is zero-terminated)
49 **
50 **  vbufprint() is a variant that accepts a va_list argument
51 **/
52
53extern char*   vbufprint(char*  buffer, char*  buffend, const char*  fmt, va_list  args );
54extern char*   bufprint (char*  buffer, char*  buffend, const char*  fmt, ... );
55
56/** USEFUL DIRECTORY SUPPORT
57 **
58 **  bufprint_add_dir() appends the application's directory to a given bounded buffer
59 **
60 **  bufprint_config_path() appends the applications' user-specific configuration directory
61 **  to a bounded buffer. on Unix this is usually ~/.android, and something a bit more
62 **  complex on Windows
63 **
64 **  bufprint_config_file() appends the name of a file or directory relative to the
65 **  user-specific configuration directory to a bounded buffer. this really is equivalent
66 **  to concat-ing the config path + path separator + 'suffix'
67 **
68 **  bufprint_temp_dir() appends the temporary directory's path to a given bounded buffer
69 **
70 **  bufprint_temp_file() appens the name of a file or directory relative to the
71 **  temporary directory. equivalent to concat-ing the temp path + path separator + 'suffix'
72 **/
73
74extern char*  bufprint_app_dir    (char*  buffer, char*  buffend);
75extern char*  bufprint_config_path(char*  buffer, char*  buffend);
76extern char*  bufprint_config_file(char*  buffer, char*  buffend, const char*  suffix);
77extern char*  bufprint_temp_dir   (char*  buffer, char*  buffend);
78extern char*  bufprint_temp_file  (char*  buffer, char*  buffend, const char*  suffix);
79
80ANDROID_END_HEADER
81
82#endif /* _ANDROID_UTILS_BUFPRINT_H */
83