← Back to branch summary

~ubuntu-branches/ubuntu/karmic/firebird2.1/karmic

« back to all changes in this revision

Viewing changes to src/common/classes/MsgPrint.h

  • Committer: Bazaar Package Importer
  • Author(s): Damyan Ivanov
  • Date: 2008-05-26 23:59:25 UTC
  • Revision ID: james.westby@ubuntu.com-20080526235925-2pnqj6nxpppoeaer
Tags: upstream-2.1.0.17798-0.ds2
Import upstream version 2.1.0.17798-0.ds2

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/common/classes/MsgPrint.h
 
1
/*
 
2
 *  The contents of this file are subject to the Initial
 
3
 *  Developer's Public License Version 1.0 (the "License");
 
4
 *  you may not use this file except in compliance with the
 
5
 *  License. You may obtain a copy of the License at
 
6
 *  http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_idpl.
 
7
 *
 
8
 *  Software distributed under the License is distributed AS IS,
 
9
 *  WITHOUT WARRANTY OF ANY KIND, either express or implied.
 
10
 *  See the License for the specific language governing rights
 
11
 *  and limitations under the License.
 
12
 *
 
13
 *  The Original Code was created by Claudio Valderrama on 3-Mar-2007
 
14
 *  for the Firebird Open Source RDBMS project.
 
15
 *
 
16
 *  Copyright (c) 2007 Claudio Valderrama
 
17
 *  and all contributors signed below.
 
18
 *
 
19
 *  All Rights Reserved.
 
20
 *  Contributor(s): ______________________________________.
 
21
 *
 
22
 */
 
23
 
 
24
 
 
25
// Localized messages type-safe printing facility.
 
26
 
 
27
#ifndef FB_MSGPRINT_H
 
28
#define FB_MSGPRINT_H
 
29
 
 
30
#include "SafeArg.h"
 
31
 
 
32
 
 
33
namespace MsgFormat
 
34
{
 
35
class BaseStream;
 
36
 
 
37
// Here we have to routines that print a message that contains placeholders for
 
38
// the parameters in a SafeArg object. The placeholders are @n where n can go
 
39
// from 1 to 7. Since the schema is positional, the same parameter can be
 
40
// referenced as many times as needed inside a format message.
 
41
// The routines rely on the parameters provided to SafeArg for knowing the type,
 
42
// therefore remember to pass arguments by value/reference not by pointer (except
 
43
// strings and UCHAR strings, of course).
 
44
// The generic usage is:
 
45
// 1.- Create an object of a class derived from the abstract BaseStream (look at
 
46
// BaseStream.h) and pass to its constructor the needed argument.
 
47
// 2.- Create an object of class SafeArg.
 
48
// 3.- Push the parameters into the SafeArg object.
 
49
// 4.- Pass the stream object, the format string and the SafeArg object to the
 
50
// full MsgPrint routine.
 
51
// In practice, most places in the code don't need such functionality and steps
 
52
// may be omitted by constructing unnamed objects on the fly.
 
53
// Example of full routine using on the fly objects:
 
54
// char s[100];
 
55
// MsgPrint(StringStream(s, sizeof(s)), "Value is @1\n", SafeArg() << 468);
 
56
// But there's a simplified version that does this for you already:
 
57
// MsgPrint(s, sizeof(s), "Value is @1\n", SafeArg() << 468);
 
58
// Now "s" can be used elsewhere or can be printed to the screen using another
 
59
// overloaded function in the MsgPrint family: MsgPrint(s);
 
60
// With s being too small, we get:
 
61
// char s[15];
 
62
// MsgPrint(s, sizeof(s), "Excess @1\n", 3.1415926);
 
63
// Now s is "Excess 3.14..." and the \0 used the last available position.
 
64
// Another typicaly usage may be:
 
65
// SafeArg sa(intarr, FB_NELEM(intarr));  <- array of five integers
 
66
// MsgPrint("@1 @5 @2 @4 @3\n", sa); <- prints intarr[0], [4], [1], [3] and [2].
 
67
// Remember the positions used by MsgPrint start at one, not zero.
 
68
// Now we clean the structure and start fresh:
 
69
// MsgPrint("New argument is @1\n", sa.clear() << 3.55);
 
70
// It's possible to address more data types as targets to be filled by MsgPrint
 
71
// by creating a derivative of BaseStream and creating a shortcut MsgPrint like D
 
72
// that handles the creation of the new BaseStream object internally.
 
73
//
 
74
// The routine fb_msg_format is the safe type replacement of gds__msg_format and
 
75
// takes almost the same parameters as the old function with the difference that
 
76
// the old function needs five fixed parameters whereas the new uses the MsgFormat
 
77
// class to describe parameters and the format string that's retrieved from the
 
78
// msg.fdb database uses @n placeholders insteaf of printf formatting arguments.
 
79
// In case the function detects % in the format, it calls snprintf.
 
80
 
 
81
 
 
82
// A. The basic routine.
 
83
int MsgPrint(BaseStream& out_stream, const char* format, const SafeArg& arg);
 
84
 
 
85
// B. Printf replacement. Output to stdout.
 
86
int MsgPrint(const char* format, const SafeArg& arg);
 
87
 
 
88
// C. Print without arguments to stdout.
 
89
int MsgPrint(const char* format);
 
90
 
 
91
// D. Print to a string, without buffer overrun.
 
92
int MsgPrint(char* plainstring, unsigned int s_size, 
 
93
                         const char* format, const SafeArg& arg);
 
94
                         
 
95
// E. Prints a formatted string into stderr and flushed the buffer.
 
96
int MsgPrintErr(const char* format, const SafeArg& arg);
 
97
} // namespace
 
98
 
 
99
// Type safe replacement of the old gds__msg_format.
 
100
int fb_msg_format(void*        handle,
 
101
                                  USHORT       facility,
 
102
                                  USHORT       number,
 
103
                                  unsigned int bsize,
 
104
                                  TEXT*        buffer,
 
105
                                  const        MsgFormat::SafeArg& arg);
 
106
 
 
107
#endif // FB_MSGPRINT_H