blob: 1a1cf530f5f3bd9078f5195930f7375485d7f63e [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 Thompson1656e6a2013-08-29 18:01:48 -070037 Component(const std::vector<unsigned char>& 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 Thompsona166b732013-08-27 16:09:29 -070047 Component(const unsigned char *value, unsigned int 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 Thompson995aba52013-09-12 12:04:52 -070071 componentStruct.value = (unsigned char*)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
112 makeFromEscapedString(const char *escapedString, unsigned int beginOffset, unsigned int 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 Thompsone5f839b2013-06-28 12:50:38 -0700174 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700175 void
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700176 appendComponent(const unsigned char *value, unsigned int valueLength)
Jeff Thompson0f743452013-09-12 14:23:18 -0700177 {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700178 components_.push_back(Component(value, valueLength));
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700179 }
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700180
181 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700182 * Append a new component, copying from value.
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700183 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700184 void
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700185 appendComponent(const std::vector<unsigned char>& value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700186 {
187 components_.push_back(value);
188 }
189
Jeff Thompson0050abe2013-09-17 12:50:25 -0700190 void
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700191 appendComponent(const Blob &value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700192 {
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700193 components_.push_back(value);
194 }
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700195
196 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700197 * @deprecated Use appendComponent.
198 */
199 void
200 addComponent(const unsigned char *value, unsigned int valueLength)
201 {
202 appendComponent(value, valueLength);
203 }
204
205 /**
206 * @deprecated Use appendComponent.
207 */
208 void
209 addComponent(const std::vector<unsigned char>& value)
210 {
211 appendComponent(value);
212 }
213
214 /**
215 * @deprecated Use appendComponent.
216 */
217 void
218 addComponent(const Blob &value)
219 {
220 appendComponent(value);
221 }
222
223 /**
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700224 * Clear all the components.
225 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700226 void
227 clear() {
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700228 components_.clear();
229 }
230
231 /**
232 * Get the number of components.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700233 * @return The number of components.
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700234 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700235 unsigned int
236 getComponentCount() const {
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700237 return components_.size();
238 }
239
Jeff Thompson0050abe2013-09-17 12:50:25 -0700240 const Component&
241 getComponent(unsigned int i) const { return components_[i]; }
Jeff Thompson443398d2013-07-02 19:45:46 -0700242
Jeff Thompsone6063512013-07-01 15:11:28 -0700243 /**
Jeff Thompsond0159d72013-09-23 13:34:15 -0700244 * Get a new name, constructed as a subset of components.
245 * @param iStartComponent The index if the first component to get.
246 * @param nComponents The number of components starting at iStartComponent.
247 * @return A new name.
248 */
249 Name
250 getSubName(size_t iStartComponent, size_t nComponents) const;
251
252 /**
253 * Get a new name, constructed as a subset of components starting at iStartComponent until the end of the name.
254 * @param iStartComponent The index if the first component to get.
255 * @return A new name.
256 */
257 Name
258 getSubName(size_t iStartComponent) const;
259
260 /**
261 * Return a new Name with the first nComponents components of this Name.
262 * @param nComponents The number of prefix components.
263 * @return A new Name.
264 */
265 Name
266 getPrefix(size_t nComponents) const
267 {
268 return getSubName(0, nComponents);
269 }
270
271 /**
Jeff Thompsone6063512013-07-01 15:11:28 -0700272 * Encode this name as a URI.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700273 * @return The encoded URI.
Jeff Thompsone6063512013-07-01 15:11:28 -0700274 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700275 std::string
276 toUri() const;
Jeff Thompsone6063512013-07-01 15:11:28 -0700277
Jeff Thompson21844fc2013-08-08 14:52:51 -0700278 /**
279 * @deprecated Use toUri().
280 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700281 std::string
282 to_uri() const
Jeff Thompson21844fc2013-08-08 14:52:51 -0700283 {
284 return toUri();
285 }
Jeff Thompson8aac1992013-08-12 17:26:02 -0700286
287 /**
288 * Append a component with the encoded segment number.
289 * @param segment The segment number.
290 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700291 void
292 appendSegment(unsigned long segment)
Jeff Thompson8aac1992013-08-12 17:26:02 -0700293 {
Jeff Thompson46411c92013-09-13 19:31:25 -0700294 components_.push_back(Component(Component::makeSegment(segment)));
Jeff Thompson8aac1992013-08-12 17:26:02 -0700295 }
Jeff Thompsoncc35cd42013-08-20 12:23:14 -0700296
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700297 /**
298 * Check if the N components of this name are the same as the first N components of the given name.
299 * @param name The Name to check.
300 * @return true if this matches the given name, otherwise false. This always returns true if this name is empty.
301 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700302 bool
303 match(const Name& name) const;
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700304
305 /**
306 * Write the value to result, escaping characters according to the NDN URI Scheme.
307 * This also adds "..." to a value with zero or more ".".
308 * @param value the buffer with the value to escape
309 * @param result the string stream to write to.
310 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700311 static void
312 toEscapedString(const std::vector<unsigned char>& value, std::ostringstream& result);
Jeff Thompson21844fc2013-08-08 14:52:51 -0700313
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700314 /**
315 * Convert the value by escaping characters according to the NDN URI Scheme.
316 * This also adds "..." to a value with zero or more ".".
317 * @param value the buffer with the value to escape
318 * @return The escaped string.
319 */
320 static std::string
321 toEscapedString(const std::vector<unsigned char>& value);
322
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700323private:
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700324 std::vector<Component> components_;
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700325};
326
327}
328
329#endif
330