blob: 5bf5654461bd0afcb7a97bbe1bbc958eefcd033f [file] [log] [blame]
Jeff Thompson25b4e612013-10-10 16:03:24 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
Jeff Thompson25e89382013-09-11 15:35:19 -07002/**
Jeff Thompson7687dc02013-09-13 11:54:07 -07003 * Copyright (C) 2013 Regents of the University of California.
4 * @author: Jeff Thompson <jefft0@remap.ucla.edu>
Jeff Thompson25e89382013-09-11 15:35:19 -07005 * See COPYING for copyright and distribution information.
6 */
7
8#ifndef NDN_BLOB_HPP
9#define NDN_BLOB_HPP
10
11#include "../common.hpp"
Jeff Thompson25b4e612013-10-10 16:03:24 -070012
13struct ndn_Blob;
Jeff Thompson25e89382013-09-11 15:35:19 -070014
15namespace ndn {
16
17/**
Jeff Thompson10ad12a2013-09-24 16:19:11 -070018 * A Blob holds a pointer to an immutable byte array implemented as const std::vector<uint8_t>.
Jeff Thompson0e6d1422013-09-12 11:36:37 -070019 * This is like a JavaScript string which is a pointer to an immutable string.
20 * It is OK to pass a pointer to the string because the new owner can't change the bytes
Jeff Thompson675d71a2013-09-12 10:57:37 -070021 * of the string. However, like a JavaScript string, it is possible to change the pointer, and so this does allow
Jeff Thompson0e6d1422013-09-12 11:36:37 -070022 * the copy constructor and assignment to change the pointer. Also remember that the pointer can be null.
Jeff Thompson10ad12a2013-09-24 16:19:11 -070023 * (Note that we could have made Blob derive directly from vector<uint8_t> and then explicitly use
Jeff Thompsonc69163b2013-10-12 13:49:50 -070024 * a pointer to it like Blob, but this does not enforce immutability because we can't declare
Jeff Thompson10ad12a2013-09-24 16:19:11 -070025 * Blob as derived from const vector<uint8_t>.)
Jeff Thompson25e89382013-09-11 15:35:19 -070026 */
Jeff Thompson10ad12a2013-09-24 16:19:11 -070027class Blob : public ptr_lib::shared_ptr<const std::vector<uint8_t> > {
Jeff Thompson25e89382013-09-11 15:35:19 -070028public:
29 /**
Jeff Thompson0e6d1422013-09-12 11:36:37 -070030 * Create a new Blob with a null pointer.
31 */
32 Blob()
33 {
34 }
35
36 /**
Jeff Thompson25e89382013-09-11 15:35:19 -070037 * Create a new Blob with an immutable copy of the given array.
38 * @param value A pointer to the byte array which is copied.
39 * @param valueLength The length of value.
40 */
Jeff Thompson97223af2013-09-24 17:01:27 -070041 Blob(const uint8_t* value, size_t valueLength)
Jeff Thompson10ad12a2013-09-24 16:19:11 -070042 : ptr_lib::shared_ptr<const std::vector<uint8_t> >(new std::vector<uint8_t>(value, value + valueLength))
Jeff Thompson25e89382013-09-11 15:35:19 -070043 {
44 }
45
46 /**
47 * Create a new Blob with an immutable copy of the array in the given vector.
Jeff Thompson675d71a2013-09-12 10:57:37 -070048 * If you want to transfer the array without copying, the the vector has to start as a
Jeff Thompson10ad12a2013-09-24 16:19:11 -070049 * ptr_lib::shared_ptr<std::vector<uint8_t> > and you can use the Blob constructor with this type.
Jeff Thompson25e89382013-09-11 15:35:19 -070050 * @param value A reference to a vector which is copied.
51 */
Jeff Thompson10ad12a2013-09-24 16:19:11 -070052 Blob(const std::vector<uint8_t> &value)
53 : ptr_lib::shared_ptr<const std::vector<uint8_t> >(new std::vector<uint8_t>(value))
Jeff Thompson25e89382013-09-11 15:35:19 -070054 {
55 }
56
57 /**
Jeff Thompson93034532013-10-08 11:52:43 -070058 * Create a new Blob with an immutable copy of the array in the given Blob struct.
59 * @param blobStruct The C ndn_Blob struct to receive the pointer.
60 */
Jeff Thompson25b4e612013-10-10 16:03:24 -070061 Blob(const struct ndn_Blob& blobStruct);
Jeff Thompson93034532013-10-08 11:52:43 -070062
63 /**
Jeff Thompson25e89382013-09-11 15:35:19 -070064 * Create a new Blob to point to an existing byte array. IMPORTANT: After calling this constructor,
Jeff Thompson0e6d1422013-09-12 11:36:37 -070065 * if you keep a pointer to the array then you must treat the array as immutable and promise not to change it.
Jeff Thompson25e89382013-09-11 15:35:19 -070066 * @param value A pointer to a vector with the byte array. This takes another reference and does not copy the bytes.
67 */
Jeff Thompson10ad12a2013-09-24 16:19:11 -070068 Blob(const ptr_lib::shared_ptr<std::vector<uint8_t> > &value)
69 : ptr_lib::shared_ptr<const std::vector<uint8_t> >(value)
Jeff Thompson25e89382013-09-11 15:35:19 -070070 {
71 }
Jeff Thompson10ad12a2013-09-24 16:19:11 -070072 Blob(const ptr_lib::shared_ptr<const std::vector<uint8_t> > &value)
73 : ptr_lib::shared_ptr<const std::vector<uint8_t> >(value)
Jeff Thompsond0be4712013-09-12 15:20:05 -070074 {
75 }
Jeff Thompson25e89382013-09-11 15:35:19 -070076
77 /**
Jeff Thompson25e89382013-09-11 15:35:19 -070078 * Return the length of the immutable byte array.
79 */
Jeff Thompson97223af2013-09-24 17:01:27 -070080 size_t
Jeff Thompson0050abe2013-09-17 12:50:25 -070081 size() const
Jeff Thompson25e89382013-09-11 15:35:19 -070082 {
Jeff Thompsone5ddbed2013-09-12 12:19:31 -070083 if (*this)
84 return (*this)->size();
85 else
86 return 0;
Jeff Thompson25e89382013-09-11 15:35:19 -070087 }
88
89 /**
Jeff Thompsone5ddbed2013-09-12 12:19:31 -070090 * Return a const pointer to the first byte of the immutable byte array, or 0 if the pointer is null.
Jeff Thompson25e89382013-09-11 15:35:19 -070091 */
Jeff Thompson10ad12a2013-09-24 16:19:11 -070092 const uint8_t*
Jeff Thompson0050abe2013-09-17 12:50:25 -070093 buf() const
Jeff Thompson25e89382013-09-11 15:35:19 -070094 {
Jeff Thompsone5ddbed2013-09-12 12:19:31 -070095 if (*this)
Jeff Thompsonf6d5a622013-09-12 12:21:00 -070096 return &(*this)->front();
Jeff Thompsone5ddbed2013-09-12 12:19:31 -070097 else
98 return 0;
Jeff Thompson25e89382013-09-11 15:35:19 -070099 }
Jeff Thompson93034532013-10-08 11:52:43 -0700100
101 /**
102 * Set the blobStruct to point to this Blob's byte array, without copying any memory.
103 * WARNING: The resulting pointer in blobStruct is invalid after a further use of this object which could reallocate memory.
104 * @param blobStruct The C ndn_Blob struct to receive the pointer.
105 */
106 void
Jeff Thompson25b4e612013-10-10 16:03:24 -0700107 get(struct ndn_Blob& blobStruct) const;
Jeff Thompson25e89382013-09-11 15:35:19 -0700108};
109
110}
111
112#endif