blob: 256bd5987699dfab5f7a5f1061778ffab466514f [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 Thompson3549ef32013-09-25 14:05:17 -0700145 Name(const char* uri)
Jeff Thompson67515bd2013-08-15 17:43:22 -0700146 {
147 set(uri);
148 }
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700149
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700150 /**
Jeff Thompson3549ef32013-09-25 14:05:17 -0700151 * Parse the uri according to the NDN URI Scheme and create the name with the components.
152 * @param uri The URI string.
153 */
154 Name(const std::string& uri)
155 {
156 set(uri.c_str());
157 }
158
159 /**
Jeff Thompson016ed642013-07-02 14:39:06 -0700160 * Set the nameStruct to point to the components in this name, without copying any memory.
161 * 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 -0700162 * @param nameStruct A C ndn_Name struct where the components array is already allocated.
Jeff Thompson016ed642013-07-02 14:39:06 -0700163 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700164 void
165 get(struct ndn_Name& nameStruct) const;
Jeff Thompson016ed642013-07-02 14:39:06 -0700166
167 /**
Jeff Thompson8b27e3a2013-07-03 18:19:53 -0700168 * Clear this name, and set the components by copying from the name struct.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700169 * @param nameStruct A C ndn_Name struct
Jeff Thompsonb468c312013-07-01 17:50:14 -0700170 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700171 void
172 set(const struct ndn_Name& nameStruct);
Jeff Thompsonb468c312013-07-01 17:50:14 -0700173
174 /**
Jeff Thompson67515bd2013-08-15 17:43:22 -0700175 * Parse the uri according to the NDN URI Scheme and set the name with the components.
176 * @param uri The URI string.
177 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700178 void
179 set(const char *uri);
Jeff Thompson67515bd2013-08-15 17:43:22 -0700180
181 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700182 * Append a new component, copying from value of length valueLength.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700183 * @return This name so that you can chain calls to append.
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700184 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700185 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700186 append(const uint8_t *value, size_t valueLength)
Jeff Thompson0f743452013-09-12 14:23:18 -0700187 {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700188 components_.push_back(Component(value, valueLength));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700189 return *this;
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700190 }
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700191
192 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700193 * Append a new component, copying from value.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700194 * @return This name so that you can chain calls to append.
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700195 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700196 Name&
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700197 append(const std::vector<uint8_t>& value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700198 {
199 components_.push_back(value);
Jeff Thompson26b0d792013-09-23 16:19:01 -0700200 return *this;
Jeff Thompson0f743452013-09-12 14:23:18 -0700201 }
202
Jeff Thompson26b0d792013-09-23 16:19:01 -0700203 Name&
204 append(const Blob &value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700205 {
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700206 components_.push_back(value);
Jeff Thompson26b0d792013-09-23 16:19:01 -0700207 return *this;
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700208 }
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700209
Jeff Thompson21eb7212013-09-26 09:05:40 -0700210 Name&
211 append(const Component &value)
212 {
213 components_.push_back(value);
214 return *this;
215 }
216
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700217 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700218 * Append the components of the given name to this name.
219 * @param name The Name with components to append.
220 * @return This name so that you can chain calls to append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700221 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700222 Name&
223 append(const Name& name);
224
225 /**
226 * @deprecated Use append.
227 */
228 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700229 appendComponent(const uint8_t *value, size_t valueLength)
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700230 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700231 return append(value, valueLength);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700232 }
233
234 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700235 * @deprecated Use append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700236 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700237 Name&
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700238 appendComponent(const std::vector<uint8_t>& value)
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700239 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700240 return append(value);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700241 }
242
243 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700244 * @deprecated Use append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700245 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700246 Name&
247 appendComponent(const Blob &value)
248 {
249 return append(value);
250 }
251
252 /**
253 * @deprecated Use append.
254 */
255 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700256 addComponent(const uint8_t *value, size_t valueLength)
Jeff Thompson26b0d792013-09-23 16:19:01 -0700257 {
258 return append(value, valueLength);
259 }
260
261 /**
262 * @deprecated Use append.
263 */
264 Name&
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700265 addComponent(const std::vector<uint8_t>& value)
Jeff Thompson26b0d792013-09-23 16:19:01 -0700266 {
267 return append(value);
268 }
269
270 /**
271 * @deprecated Use append.
272 */
273 Name&
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700274 addComponent(const Blob &value)
275 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700276 return append(value);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700277 }
278
279 /**
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700280 * Clear all the components.
281 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700282 void
283 clear() {
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700284 components_.clear();
285 }
286
287 /**
288 * Get the number of components.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700289 * @return The number of components.
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700290 */
Jeff Thompson97223af2013-09-24 17:01:27 -0700291 size_t
Jeff Thompson0050abe2013-09-17 12:50:25 -0700292 getComponentCount() const {
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700293 return components_.size();
294 }
295
Jeff Thompson0050abe2013-09-17 12:50:25 -0700296 const Component&
Jeff Thompson97223af2013-09-24 17:01:27 -0700297 getComponent(size_t i) const { return components_[i]; }
Jeff Thompson443398d2013-07-02 19:45:46 -0700298
Jeff Thompsone6063512013-07-01 15:11:28 -0700299 /**
Jeff Thompsond0159d72013-09-23 13:34:15 -0700300 * Get a new name, constructed as a subset of components.
301 * @param iStartComponent The index if the first component to get.
302 * @param nComponents The number of components starting at iStartComponent.
303 * @return A new name.
304 */
305 Name
306 getSubName(size_t iStartComponent, size_t nComponents) const;
307
308 /**
309 * Get a new name, constructed as a subset of components starting at iStartComponent until the end of the name.
310 * @param iStartComponent The index if the first component to get.
311 * @return A new name.
312 */
313 Name
314 getSubName(size_t iStartComponent) const;
315
316 /**
317 * Return a new Name with the first nComponents components of this Name.
318 * @param nComponents The number of prefix components.
319 * @return A new Name.
320 */
321 Name
322 getPrefix(size_t nComponents) const
323 {
324 return getSubName(0, nComponents);
325 }
326
327 /**
Jeff Thompsone6063512013-07-01 15:11:28 -0700328 * Encode this name as a URI.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700329 * @return The encoded URI.
Jeff Thompsone6063512013-07-01 15:11:28 -0700330 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700331 std::string
332 toUri() const;
Jeff Thompsone6063512013-07-01 15:11:28 -0700333
Jeff Thompson21844fc2013-08-08 14:52:51 -0700334 /**
335 * @deprecated Use toUri().
336 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700337 std::string
338 to_uri() const
Jeff Thompson21844fc2013-08-08 14:52:51 -0700339 {
340 return toUri();
341 }
Jeff Thompson26b0d792013-09-23 16:19:01 -0700342
Jeff Thompson8aac1992013-08-12 17:26:02 -0700343 /**
344 * Append a component with the encoded segment number.
345 * @param segment The segment number.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700346 * @return This name so that you can chain calls to append.
347 */
348 Name&
Jeff Thompson0050abe2013-09-17 12:50:25 -0700349 appendSegment(unsigned long segment)
Jeff Thompson8aac1992013-08-12 17:26:02 -0700350 {
Jeff Thompson46411c92013-09-13 19:31:25 -0700351 components_.push_back(Component(Component::makeSegment(segment)));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700352 return *this;
Jeff Thompson8aac1992013-08-12 17:26:02 -0700353 }
Jeff Thompsoncc35cd42013-08-20 12:23:14 -0700354
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700355 /**
356 * Check if the N components of this name are the same as the first N components of the given name.
357 * @param name The Name to check.
358 * @return true if this matches the given name, otherwise false. This always returns true if this name is empty.
359 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700360 bool
361 match(const Name& name) const;
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700362
363 /**
364 * Write the value to result, escaping characters according to the NDN URI Scheme.
365 * This also adds "..." to a value with zero or more ".".
366 * @param value the buffer with the value to escape
367 * @param result the string stream to write to.
368 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700369 static void
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700370 toEscapedString(const std::vector<uint8_t>& value, std::ostringstream& result);
Jeff Thompson21844fc2013-08-08 14:52:51 -0700371
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700372 /**
373 * Convert the value by escaping characters according to the NDN URI Scheme.
374 * This also adds "..." to a value with zero or more ".".
375 * @param value the buffer with the value to escape
376 * @return The escaped string.
377 */
378 static std::string
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700379 toEscapedString(const std::vector<uint8_t>& value);
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700380
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700381private:
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700382 std::vector<Component> components_;
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700383};
384
385}
386
387#endif
388