1 /*
2 * Copyright 2015 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.handler.codec.dns;
17
18 import io.netty.util.ReferenceCounted;
19
20 /**
21 * The superclass which contains core information concerning a {@link DnsQuery} and a {@link DnsResponse}.
22 */
23 public interface DnsMessage extends ReferenceCounted {
24
25 /**
26 * Returns the {@code ID} of this DNS message.
27 */
28 int id();
29
30 /**
31 * Sets the {@code ID} of this DNS message.
32 */
33 DnsMessage setId(int id);
34
35 /**
36 * Returns the {@code opCode} of this DNS message.
37 */
38 DnsOpCode opCode();
39
40 /**
41 * Sets the {@code opCode} of this DNS message.
42 */
43 DnsMessage setOpCode(DnsOpCode opCode);
44
45 /**
46 * Returns the {@code RD} (recursion desired} field of this DNS message.
47 */
48 boolean isRecursionDesired();
49
50 /**
51 * Sets the {@code RD} (recursion desired} field of this DNS message.
52 */
53 DnsMessage setRecursionDesired(boolean recursionDesired);
54
55 /**
56 * Returns the {@code Z} (reserved for future use) field of this DNS message.
57 */
58 int z();
59
60 /**
61 * Sets the {@code Z} (reserved for future use) field of this DNS message.
62 */
63 DnsMessage setZ(int z);
64
65 /**
66 * Returns the number of records in the specified {@code section} of this DNS message.
67 */
68 int count(DnsSection section);
69
70 /**
71 * Returns the number of records in this DNS message.
72 */
73 int count();
74
75 /**
76 * Returns the first record in the specified {@code section} of this DNS message.
77 * When the specified {@code section} is {@link DnsSection#QUESTION}, the type of the returned record is
78 * always {@link DnsQuestion}.
79 *
80 * @return {@code null} if this message doesn't have any records in the specified {@code section}
81 */
82 <T extends DnsRecord> T recordAt(DnsSection section);
83
84 /**
85 * Returns the record at the specified {@code index} of the specified {@code section} of this DNS message.
86 * When the specified {@code section} is {@link DnsSection#QUESTION}, the type of the returned record is
87 * always {@link DnsQuestion}.
88 *
89 * @throws IndexOutOfBoundsException if the specified {@code index} is out of bounds
90 */
91 <T extends DnsRecord> T recordAt(DnsSection section, int index);
92
93 /**
94 * Sets the specified {@code section} of this DNS message to the specified {@code record},
95 * making it a single-record section. When the specified {@code section} is {@link DnsSection#QUESTION},
96 * the specified {@code record} must be a {@link DnsQuestion}.
97 */
98 DnsMessage setRecord(DnsSection section, DnsRecord record);
99
100 /**
101 * Sets the specified {@code record} at the specified {@code index} of the specified {@code section}
102 * of this DNS message. When the specified {@code section} is {@link DnsSection#QUESTION},
103 * the specified {@code record} must be a {@link DnsQuestion}.
104 *
105 * @return the old record
106 * @throws IndexOutOfBoundsException if the specified {@code index} is out of bounds
107 */
108 <T extends DnsRecord> T setRecord(DnsSection section, int index, DnsRecord record);
109
110 /**
111 * Adds the specified {@code record} at the end of the specified {@code section} of this DNS message.
112 * When the specified {@code section} is {@link DnsSection#QUESTION}, the specified {@code record}
113 * must be a {@link DnsQuestion}.
114 */
115 DnsMessage addRecord(DnsSection section, DnsRecord record);
116
117 /**
118 * Adds the specified {@code record} at the specified {@code index} of the specified {@code section}
119 * of this DNS message. When the specified {@code section} is {@link DnsSection#QUESTION}, the specified
120 * {@code record} must be a {@link DnsQuestion}.
121 *
122 * @throws IndexOutOfBoundsException if the specified {@code index} is out of bounds
123 */
124 DnsMessage addRecord(DnsSection section, int index, DnsRecord record);
125
126 /**
127 * Removes the record at the specified {@code index} of the specified {@code section} from this DNS message.
128 * When the specified {@code section} is {@link DnsSection#QUESTION}, the type of the returned record is
129 * always {@link DnsQuestion}.
130 *
131 * @return the removed record
132 */
133 <T extends DnsRecord> T removeRecord(DnsSection section, int index);
134
135 /**
136 * Removes all the records in the specified {@code section} of this DNS message.
137 */
138 DnsMessage clear(DnsSection section);
139
140 /**
141 * Removes all the records in this DNS message.
142 */
143 DnsMessage clear();
144
145 @Override
146 DnsMessage touch();
147
148 @Override
149 DnsMessage touch(Object hint);
150
151 @Override
152 DnsMessage retain();
153
154 @Override
155 DnsMessage retain(int increment);
156 }