1 #pragma once
2 
3 #include <cstdint>
4 #include <memory>
5 #include <string>
6 #include <vector>
7 
8 namespace blobs
9 {
10 
11 enum class BlobOEMCommands : std::uint8_t
12 {
13     bmcBlobGetCount = 0,
14     bmcBlobEnumerate = 1,
15     bmcBlobOpen = 2,
16     bmcBlobRead = 3,
17     bmcBlobWrite = 4,
18     bmcBlobCommit = 5,
19     bmcBlobClose = 6,
20     bmcBlobDelete = 7,
21     bmcBlobStat = 8,
22     bmcBlobSessionStat = 9,
23     bmcBlobWriteMeta = 10,
24 };
25 
26 enum OpenFlags
27 {
28     read = (1 << 0),
29     write = (1 << 1),
30     /* bits 3-7 reserved. */
31     /* bits 8-15 given blob-specific definitions */
32 };
33 
34 enum StateFlags
35 {
36     open_read = (1 << 0),
37     open_write = (1 << 1),
38     committing = (1 << 2),
39     committed = (1 << 3),
40     commit_error = (1 << 4),
41 };
42 
43 struct BlobMeta
44 {
45     uint16_t blobState;
46     uint32_t size;
47     std::vector<uint8_t> metadata;
48 
operator ==blobs::BlobMeta49     bool operator==(const BlobMeta& rhs) const
50     {
51         return (this->blobState == rhs.blobState && this->size == rhs.size &&
52                 this->metadata == rhs.metadata);
53     }
54 };
55 
56 /*
57  * All blob specific objects implement this interface.
58  */
59 class GenericBlobInterface
60 {
61   public:
62     virtual ~GenericBlobInterface() = default;
63 
64     /**
65      * Checks if the handler will manage this file path.
66      *
67      * @param[in] blobId.
68      * @return bool whether it will manage the file path.
69      */
70     virtual bool canHandleBlob(const std::string& path) = 0;
71 
72     /**
73      * Return the name(s) of the blob(s).  Used during GetCount.
74      *
75      * @return List of blobIds this handler manages.
76      */
77     virtual std::vector<std::string> getBlobIds() = 0;
78 
79     /**
80      * Attempt to delete the blob specified by the path.
81      *
82      * @param[in] path - the blobId to try and delete.
83      * @return bool - whether it was able to delete the blob.
84      */
85     virtual bool deleteBlob(const std::string& path) = 0;
86 
87     /**
88      * Return metadata about the blob.
89      *
90      * @param[in] path - the blobId for metadata.
91      * @param[in,out] meta - a pointer to a blobmeta.
92      * @return bool - true if it was successful.
93      */
94     virtual bool stat(const std::string& path, BlobMeta* meta) = 0;
95 
96     /* The methods below are per session. */
97 
98     /**
99      * Attempt to open a session from this path.
100      *
101      * @param[in] session - the session id.
102      * @param[in] flags - the open flags.
103      * @param[in] path - the blob path.
104      * @return bool - was able to open the session.
105      */
106     virtual bool open(uint16_t session, uint16_t flags,
107                       const std::string& path) = 0;
108 
109     /**
110      * Attempt to read from a blob.
111      *
112      * @param[in] session - the session id.
113      * @param[in] offset - offset into the blob.
114      * @param[in] requestedSize - number of bytes to read.
115      * @return Bytes read back (0 length on error).
116      */
117     virtual std::vector<uint8_t> read(uint16_t session, uint32_t offset,
118                                       uint32_t requestedSize) = 0;
119 
120     /**
121      * Attempt to write to a blob.
122      *
123      * @param[in] session - the session id.
124      * @param[in] offset - offset into the blob.
125      * @param[in] data - the data to write.
126      * @return bool - was able to write.
127      */
128     virtual bool write(uint16_t session, uint32_t offset,
129                        const std::vector<uint8_t>& data) = 0;
130 
131     /**
132      * Attempt to write metadata to a blob.
133      *
134      * @param[in] session - the session id.
135      * @param[in] offset - offset into the blob.
136      * @param[in] data - the data to write.
137      * @return bool - was able to write.
138      */
139     virtual bool writeMeta(uint16_t session, uint32_t offset,
140                            const std::vector<uint8_t>& data) = 0;
141 
142     /**
143      * Attempt to commit to a blob.
144      *
145      * @param[in] session - the session id.
146      * @param[in] data - optional commit data.
147      * @return bool - was able to start commit.
148      */
149     virtual bool commit(uint16_t session, const std::vector<uint8_t>& data) = 0;
150 
151     /**
152      * Attempt to close your session.
153      *
154      * @param[in] session - the session id.
155      * @return bool - was able to close session.
156      */
157     virtual bool close(uint16_t session) = 0;
158 
159     /**
160      * Attempt to return metadata for the session's view of the blob.
161      *
162      * @param[in] session - the session id.
163      * @param[in,out] meta - pointer to update with the BlobMeta.
164      * @return bool - wether it was successful.
165      */
166     virtual bool stat(uint16_t session, BlobMeta* meta) = 0;
167 
168     /**
169      * Attempt to expire a session.  This is called when a session has been
170      * inactive for at least 10 minutes.
171      *
172      * @param[in] session - the session id.
173      * @return bool - whether the session was able to be closed.
174      */
175     virtual bool expire(uint16_t session) = 0;
176 };
177 } // namespace blobs
178 
179 #ifdef __cplusplus
180 extern "C"
181 {
182 #endif
183 
184 /**
185  * All Blob handlers need to implement this method.  It is called after
186  * loading the library to then get a handle to the blob handler.
187  *
188  * @return a unique pointer to your blob handler instance.
189  */
190 std::unique_ptr<blobs::GenericBlobInterface> createHandler();
191 
192 #ifdef __cplusplus
193 }
194 #endif
195