blob: f39d568fed93241a41db5b473d35a6d94cf0d625 [file] [log] [blame]
Jeff Thompson47eecfc2013-07-07 22:56:46 -07001/**
Jeff Thompson7687dc02013-09-13 11:54:07 -07002 * Copyright (C) 2013 Regents of the University of California.
3 * @author: Jeff Thompson <jefft0@remap.ucla.edu>
Jeff Thompson47eecfc2013-07-07 22:56:46 -07004 * See COPYING for copyright and distribution information.
Jeff Thompson9c41dfe2013-06-27 12:10:25 -07005 */
6
7#ifndef NDN_NAME_HPP
Jeff Thompson2d27e2f2013-08-09 12:55:00 -07008#define NDN_NAME_HPP
Jeff Thompson9c41dfe2013-06-27 12:10:25 -07009
10#include <vector>
Jeff Thompson443398d2013-07-02 19:45:46 -070011#include <string>
Jeff Thompsonec7789a2013-08-21 11:08:36 -070012#include <sstream>
Jeff Thompson53412192013-08-06 13:35:50 -070013#include "c/name.h"
14#include "encoding/binary-xml-wire-format.hpp"
Jeff Thompson995aba52013-09-12 12:04:52 -070015#include "util/blob.hpp"
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070016
17namespace ndn {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070018
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070019class Name {
20public:
Jeff Thompsonc1c12e42013-09-13 19:08:45 -070021 /**
Jeff Thompson46411c92013-09-13 19:31:25 -070022 * A Name::Component is holds a read-only name component value.
Jeff Thompsonc1c12e42013-09-13 19:08:45 -070023 */
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070024 class Component {
25 public:
26 /**
Jeff Thompson46411c92013-09-13 19:31:25 -070027 * Create a new Name::Component with a null value.
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070028 */
29 Component()
30 {
31 }
32
33 /**
34 * Create a new Name::Component, copying the given value.
35 * @param value The value byte array.
36 */
Jeff Thompson10ad12a2013-09-24 16:19:11 -070037 Component(const std::vector<uint8_t>& value)
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070038 : value_(value)
39 {
40 }
41
42 /**
43 * Create a new Name::Component, copying the given value.
44 * @param value Pointer to the value byte array.
45 * @param valueLen Length of value.
46 */
Jeff Thompson97223af2013-09-24 17:01:27 -070047 Component(const uint8_t *value, size_t valueLen)
Jeff Thompson995aba52013-09-12 12:04:52 -070048 : value_(value, valueLen)
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070049 {
50 }
Jeff Thompson0f743452013-09-12 14:23:18 -070051
52 /**
53 * Create a new Name::Component, taking another pointer to the Blob value.
54 * @param value A blob with a pointer to an immutable array. The pointer is copied.
55 */
56 Component(const Blob &value)
57 : value_(value)
58 {
59 }
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070060
61 /**
62 * Set the componentStruct to point to this component, without copying any memory.
63 * WARNING: The resulting pointer in componentStruct is invalid after a further use of this object which could reallocate memory.
64 * @param componentStruct The C ndn_NameComponent struct to receive the pointer.
65 */
Jeff Thompson0050abe2013-09-17 12:50:25 -070066 void
67 get(struct ndn_NameComponent& componentStruct) const
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070068 {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070069 componentStruct.valueLength = value_.size();
Jeff Thompson38d0e082013-08-12 18:07:44 -070070 if (value_.size() > 0)
Jeff Thompson10ad12a2013-09-24 16:19:11 -070071 componentStruct.value = (uint8_t*)value_.buf();
Jeff Thompson05c8c1b2013-09-12 12:47:57 -070072 else
73 componentStruct.value = 0;
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070074 }
75
Jeff Thompson0050abe2013-09-17 12:50:25 -070076 const Blob&
77 getValue() const { return value_; }
Jeff Thompson6653b0b2013-09-23 12:32:39 -070078
79 /**
80 * Write this component value to result, escaping characters according to the NDN URI Scheme.
81 * This also adds "..." to a value with zero or more ".".
82 * @param value the buffer with the value to escape
83 * @param result the string stream to write to.
84 */
85 void
Jeff Thompsond0159d72013-09-23 13:34:15 -070086 toEscapedString(std::ostringstream& result) const
Jeff Thompson6653b0b2013-09-23 12:32:39 -070087 {
88 Name::toEscapedString(*value_, result);
89 }
90
91 /**
92 * Convert this component value by escaping characters according to the NDN URI Scheme.
93 * This also adds "..." to a value with zero or more ".".
94 * @return The escaped string.
95 */
96 std::string
Jeff Thompsond0159d72013-09-23 13:34:15 -070097 toEscapedString() const
Jeff Thompson6653b0b2013-09-23 12:32:39 -070098 {
99 return Name::toEscapedString(*value_);
100 }
Jeff Thompson9bdb3b22013-09-12 12:42:13 -0700101
Jeff Thompsonc1c12e42013-09-13 19:08:45 -0700102 /**
Jeff Thompson46411c92013-09-13 19:31:25 -0700103 * Make a component value by decoding the escapedString between beginOffset and endOffset according to the NDN URI Scheme.
104 * If the escaped string is "", "." or ".." then return a Blob with a null pointer, which means this component value was not changed, and
Jeff Thompsonc1c12e42013-09-13 19:08:45 -0700105 * the component should be skipped in a URI name.
106 * @param escapedString The escaped string. It does not need to be null-terminated because we only scan to endOffset.
107 * @param beginOffset The offset in escapedString of the beginning of the portion to decode.
108 * @param endOffset The offset in escapedString of the end of the portion to decode.
Jeff Thompson46411c92013-09-13 19:31:25 -0700109 * @return The component value as a Blob, or a Blob with a null pointer if escapedString is not a valid escaped component.
Jeff Thompsonc1c12e42013-09-13 19:08:45 -0700110 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700111 static Blob
Jeff Thompson97223af2013-09-24 17:01:27 -0700112 makeFromEscapedString(const char *escapedString, size_t beginOffset, size_t endOffset);
Jeff Thompson8aac1992013-08-12 17:26:02 -0700113
114 /**
Jeff Thompson46411c92013-09-13 19:31:25 -0700115 * Make a component as the encoded segment number.
Jeff Thompson8aac1992013-08-12 17:26:02 -0700116 * @param segment The segment number.
Jeff Thompson46411c92013-09-13 19:31:25 -0700117 * @return The component value as a Blob.
Jeff Thompson8aac1992013-08-12 17:26:02 -0700118 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700119 static Blob
120 makeSegment(unsigned long segment);
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700121
122 private:
Jeff Thompson995aba52013-09-12 12:04:52 -0700123 Blob value_;
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700124 };
125
Jeff Thompson443398d2013-07-02 19:45:46 -0700126 /**
127 * Create a new Name with no components.
128 */
Jeff Thompson016ed642013-07-02 14:39:06 -0700129 Name() {
130 }
Jeff Thompson443398d2013-07-02 19:45:46 -0700131
132 /**
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700133 * Create a new Name, copying the name components.
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700134 * @param components A vector of Component
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700135 */
Jeff Thompson1656e6a2013-08-29 18:01:48 -0700136 Name(const std::vector<Component>& components)
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700137 : components_(components)
138 {
139 }
140
141 /**
Jeff Thompson443398d2013-07-02 19:45:46 -0700142 * Parse the uri according to the NDN URI Scheme and create the name with the components.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700143 * @param uri The URI string.
Jeff Thompson443398d2013-07-02 19:45:46 -0700144 */
Jeff Thompson67515bd2013-08-15 17:43:22 -0700145 Name(const char *uri)
146 {
147 set(uri);
148 }
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700149
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700150 /**
Jeff Thompson016ed642013-07-02 14:39:06 -0700151 * Set the nameStruct to point to the components in this name, without copying any memory.
152 * WARNING: The resulting pointers in nameStruct are invalid after a further use of this object which could reallocate memory.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700153 * @param nameStruct A C ndn_Name struct where the components array is already allocated.
Jeff Thompson016ed642013-07-02 14:39:06 -0700154 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700155 void
156 get(struct ndn_Name& nameStruct) const;
Jeff Thompson016ed642013-07-02 14:39:06 -0700157
158 /**
Jeff Thompson8b27e3a2013-07-03 18:19:53 -0700159 * Clear this name, and set the components by copying from the name struct.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700160 * @param nameStruct A C ndn_Name struct
Jeff Thompsonb468c312013-07-01 17:50:14 -0700161 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700162 void
163 set(const struct ndn_Name& nameStruct);
Jeff Thompsonb468c312013-07-01 17:50:14 -0700164
165 /**
Jeff Thompson67515bd2013-08-15 17:43:22 -0700166 * Parse the uri according to the NDN URI Scheme and set the name with the components.
167 * @param uri The URI string.
168 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700169 void
170 set(const char *uri);
Jeff Thompson67515bd2013-08-15 17:43:22 -0700171
172 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700173 * Append a new component, copying from value of length valueLength.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700174 * @return This name so that you can chain calls to append.
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700175 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700176 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700177 append(const uint8_t *value, size_t valueLength)
Jeff Thompson0f743452013-09-12 14:23:18 -0700178 {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700179 components_.push_back(Component(value, valueLength));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700180 return *this;
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700181 }
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700182
183 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700184 * Append a new component, copying from value.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700185 * @return This name so that you can chain calls to append.
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700186 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700187 Name&
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700188 append(const std::vector<uint8_t>& value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700189 {
190 components_.push_back(value);
Jeff Thompson26b0d792013-09-23 16:19:01 -0700191 return *this;
Jeff Thompson0f743452013-09-12 14:23:18 -0700192 }
193
Jeff Thompson26b0d792013-09-23 16:19:01 -0700194 Name&
195 append(const Blob &value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700196 {
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700197 components_.push_back(value);
Jeff Thompson26b0d792013-09-23 16:19:01 -0700198 return *this;
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700199 }
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700200
201 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700202 * Append the components of the given name to this name.
203 * @param name The Name with components to append.
204 * @return This name so that you can chain calls to append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700205 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700206 Name&
207 append(const Name& name);
208
209 /**
210 * @deprecated Use append.
211 */
212 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700213 appendComponent(const uint8_t *value, size_t valueLength)
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700214 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700215 return append(value, valueLength);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700216 }
217
218 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700219 * @deprecated Use append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700220 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700221 Name&
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700222 appendComponent(const std::vector<uint8_t>& value)
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700223 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700224 return append(value);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700225 }
226
227 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700228 * @deprecated Use append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700229 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700230 Name&
231 appendComponent(const Blob &value)
232 {
233 return append(value);
234 }
235
236 /**
237 * @deprecated Use append.
238 */
239 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700240 addComponent(const uint8_t *value, size_t valueLength)
Jeff Thompson26b0d792013-09-23 16:19:01 -0700241 {
242 return append(value, valueLength);
243 }
244
245 /**
246 * @deprecated Use append.
247 */
248 Name&
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700249 addComponent(const std::vector<uint8_t>& value)
Jeff Thompson26b0d792013-09-23 16:19:01 -0700250 {
251 return append(value);
252 }
253
254 /**
255 * @deprecated Use append.
256 */
257 Name&
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700258 addComponent(const Blob &value)
259 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700260 return append(value);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700261 }
262
263 /**
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700264 * Clear all the components.
265 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700266 void
267 clear() {
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700268 components_.clear();
269 }
270
271 /**
272 * Get the number of components.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700273 * @return The number of components.
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700274 */
Jeff Thompson97223af2013-09-24 17:01:27 -0700275 size_t
Jeff Thompson0050abe2013-09-17 12:50:25 -0700276 getComponentCount() const {
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700277 return components_.size();
278 }
279
Jeff Thompson0050abe2013-09-17 12:50:25 -0700280 const Component&
Jeff Thompson97223af2013-09-24 17:01:27 -0700281 getComponent(size_t i) const { return components_[i]; }
Jeff Thompson443398d2013-07-02 19:45:46 -0700282
Jeff Thompsone6063512013-07-01 15:11:28 -0700283 /**
Jeff Thompsond0159d72013-09-23 13:34:15 -0700284 * Get a new name, constructed as a subset of components.
285 * @param iStartComponent The index if the first component to get.
286 * @param nComponents The number of components starting at iStartComponent.
287 * @return A new name.
288 */
289 Name
290 getSubName(size_t iStartComponent, size_t nComponents) const;
291
292 /**
293 * Get a new name, constructed as a subset of components starting at iStartComponent until the end of the name.
294 * @param iStartComponent The index if the first component to get.
295 * @return A new name.
296 */
297 Name
298 getSubName(size_t iStartComponent) const;
299
300 /**
301 * Return a new Name with the first nComponents components of this Name.
302 * @param nComponents The number of prefix components.
303 * @return A new Name.
304 */
305 Name
306 getPrefix(size_t nComponents) const
307 {
308 return getSubName(0, nComponents);
309 }
310
311 /**
Jeff Thompsone6063512013-07-01 15:11:28 -0700312 * Encode this name as a URI.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700313 * @return The encoded URI.
Jeff Thompsone6063512013-07-01 15:11:28 -0700314 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700315 std::string
316 toUri() const;
Jeff Thompsone6063512013-07-01 15:11:28 -0700317
Jeff Thompson21844fc2013-08-08 14:52:51 -0700318 /**
319 * @deprecated Use toUri().
320 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700321 std::string
322 to_uri() const
Jeff Thompson21844fc2013-08-08 14:52:51 -0700323 {
324 return toUri();
325 }
Jeff Thompson26b0d792013-09-23 16:19:01 -0700326
Jeff Thompson8aac1992013-08-12 17:26:02 -0700327 /**
328 * Append a component with the encoded segment number.
329 * @param segment The segment number.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700330 * @return This name so that you can chain calls to append.
331 */
332 Name&
Jeff Thompson0050abe2013-09-17 12:50:25 -0700333 appendSegment(unsigned long segment)
Jeff Thompson8aac1992013-08-12 17:26:02 -0700334 {
Jeff Thompson46411c92013-09-13 19:31:25 -0700335 components_.push_back(Component(Component::makeSegment(segment)));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700336 return *this;
Jeff Thompson8aac1992013-08-12 17:26:02 -0700337 }
Jeff Thompsoncc35cd42013-08-20 12:23:14 -0700338
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700339 /**
340 * Check if the N components of this name are the same as the first N components of the given name.
341 * @param name The Name to check.
342 * @return true if this matches the given name, otherwise false. This always returns true if this name is empty.
343 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700344 bool
345 match(const Name& name) const;
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700346
347 /**
348 * Write the value to result, escaping characters according to the NDN URI Scheme.
349 * This also adds "..." to a value with zero or more ".".
350 * @param value the buffer with the value to escape
351 * @param result the string stream to write to.
352 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700353 static void
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700354 toEscapedString(const std::vector<uint8_t>& value, std::ostringstream& result);
Jeff Thompson21844fc2013-08-08 14:52:51 -0700355
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700356 /**
357 * Convert the value by escaping characters according to the NDN URI Scheme.
358 * This also adds "..." to a value with zero or more ".".
359 * @param value the buffer with the value to escape
360 * @return The escaped string.
361 */
362 static std::string
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700363 toEscapedString(const std::vector<uint8_t>& value);
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700364
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700365private:
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700366 std::vector<Component> components_;
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700367};
368
369}
370
371#endif
372