1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
// Copyright (C) 2012-2024 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
#ifndef DNS_RDATA_CHARSTRING_H
#define DNS_RDATA_CHARSTRING_H
#include <dns/master_lexer.h>
#include <string>
#include <vector>
#include <algorithm>
#include <stdint.h>
namespace isc {
namespace dns {
namespace rdata {
namespace generic {
namespace detail {
/// \brief Type for DNS character string.
///
/// A character string can contain any unsigned 8-bit value, so this cannot
/// be the bare char basis.
typedef std::vector<uint8_t> CharString;
/// \brief Type for DNS character string without the length prefix.
typedef std::vector<uint8_t> CharStringData;
/// \brief Convert a DNS character-string into corresponding binary data.
///
/// This helper function takes a string object that is expected to be a
/// textual representation of a valid DNS character-string, and dumps
/// the corresponding binary sequence in the given placeholder (passed
/// via the \c result parameter). It handles escape notations of
/// character-strings with a backslash ('\'), and checks the length
/// restriction.
///
/// \throw CharStringTooLong The resulting binary data are too large for a
/// valid character-string.
/// \throw InvalidRdataText Other syntax errors.
///
/// \brief str_region A string that represents a character-string.
/// \brief result A placeholder vector where the resulting data are to be
/// stored. Expected to be empty, but it's not checked.
void stringToCharString(const MasterToken::StringRegion& str_region,
CharString& result);
/// \brief Convert a DNS character-string into corresponding binary data.
///
/// This method functions similar to \c stringToCharString() except it
/// does not include the 1-octet length prefix in the \c result, and the
/// result is not limited to MAX_CHARSTRING_LEN octets.
///
/// \throw InvalidRdataText Upon syntax errors.
///
/// \brief str_region A string that represents a character-string.
/// \brief result A placeholder vector where the resulting data are to be
/// stored. Expected to be empty, but it's not checked.
void stringToCharStringData(const MasterToken::StringRegion& str_region,
CharStringData& result);
/// \brief Convert a CharString into a textual DNS character-string.
///
/// This method converts a binary 8-bit representation of a DNS
/// character string into a textual string representation, escaping any
/// special characters in the process. For example, characters like
/// double-quotes, semi-colon and backspace are prefixed with backspace
/// character, and characters not in the printable range of [0x20, 0x7e]
/// (inclusive) are converted to the \\xxx 3-digit decimal
/// representation.
///
/// \param char_string The \c CharString to convert.
/// \return A string representation of \c char_string.
std::string charStringToString(const CharString& char_string);
/// \brief Convert a CharStringData into a textual DNS character-string.
///
/// Reverse of \c stringToCharStringData(). See \c stringToCharString()
/// vs. \c stringToCharStringData().
///
/// \param char_string The \c CharStringData to convert.
/// \return A string representation of \c char_string.
std::string charStringDataToString(const CharStringData& char_string);
/// \brief Compare two CharString objects
///
/// \param self The CharString field to compare
/// \param other The CharString field to compare to
///
/// \return -1 if \c self would be sorted before \c other
/// 1 if \c self would be sorted after \c other
/// 0 if \c self and \c other are equal
int compareCharStrings(const CharString& self, const CharString& other);
/// \brief Compare two CharStringData objects
///
/// \param self The CharStringData field to compare
/// \param other The CharStringData field to compare to
///
/// \return -1 if \c self would be sorted before \c other
/// 1 if \c self would be sorted after \c other
/// 0 if \c self and \c other are equal
int compareCharStringDatas(const CharStringData& self,
const CharStringData& other);
/// \brief Convert a buffer containing a character-string to CharString
///
/// This method reads one character-string from the given buffer (in wire
/// format) and places the result in the given \c CharString object.
/// Since this is expected to be used in message parsing, the exception it
/// raises is of that type.
///
/// On success, the buffer position is advanced to the end of the char-string,
/// and the number of bytes read is returned.
///
/// \param buffer The buffer to read from.
/// \param rdata_len The total size of the rr's rdata currently being read
/// (used for integrity checks in the wire data)
/// \param target The \c CharString where the result will be stored. Any
/// existing data in the target will be overwritten.
/// \throw DNSMessageFORMERR If the available data is not enough to read
/// the character-string, or if the character-string length is out of bounds
/// \return The number of bytes read
size_t bufferToCharString(isc::util::InputBuffer& buffer, size_t rdata_len,
CharString& target);
} // namespace detail
} // namespace generic
} // namespace rdata
} // namespace dns
} // namespace isc
#endif // DNS_RDATA_CHARSTRING_H
|
