1 /*
2  * The MIT License (MIT)
3  *
4  * Copyright (c) 2018 Nathan Osman
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  */
24 
25 #ifndef LIBNITROSHARE_ITEM_H
26 #define LIBNITROSHARE_ITEM_H
27 
28 #include <QObject>
29 
30 #include <nitroshare/config.h>
31 
32 /**
33  * @brief Individual item for transfer
34  *
35  * Each item in a bundle is an instance of a class that derives from this one.
36  * Properties should be used for attributes that need to be included in the
37  * metadata sent in a transfer.
38  */
39 class NITROSHARE_EXPORT Item : public QObject
40 {
41     Q_OBJECT
42     Q_ENUMS(OpenMode)
43     Q_PROPERTY(QString type READ type)
44     Q_PROPERTY(QString name READ name)
45     Q_PROPERTY(qint64 size READ size)
46 
47 public:
48 
49     /**
50      * @brief Mode used for opening the file
51      */
52     enum OpenMode {
53         Read,
54         Write
55     };
56 
57     /**
58      * @brief Retrieve the unique identifier for the item
59      * @return identifier
60      */
61     virtual QString type() const = 0;
62 
63     /**
64      * @brief Retrieve the name of the item
65      * @return item name
66      */
67     virtual QString name() const = 0;
68 
69     /**
70      * @brief Retrieve the size of the item
71      * @return item size
72      */
73     virtual qint64 size() const;
74 
75     /**
76      * @brief Open the item for reading or writing
77      * @param openMode mode used for opening the file
78      * @return true if the item was opened
79      */
80     virtual bool open(OpenMode openMode);
81 
82     /**
83      * @brief Read data from the item
84      * @return array of bytes
85      *
86      * This method should avoid returning large amounts of data in order to
87      * avoid excess memory usage. Instead, return successive portions of the
88      * item with each call.
89      *
90      * Use the error() signal to indicate an error.
91      */
92     virtual QByteArray read();
93 
94     /**
95      * @brief Write data to the item
96      * @param data information to write
97      *
98      * Use the error() signal to indicate an error.
99      */
100     virtual void write(const QByteArray &data);
101 
102     /**
103      * @brief Close the item
104      *
105      * Use the error() signal to indicate an error.
106      */
107     virtual void close();
108 
109 Q_SIGNALS:
110 
111     /**
112      * @brief Indicate an error has occurred
113      * @param message description of the error
114      */
115     void error(const QString &message);
116 };
117 
118 #endif // LIBNITROSHARE_ITEM_H
119