Changeset 74142 in vbox for trunk

Timestamp:

Sep 7, 2018 1:29:43 PM (6 years ago)

Author:

vboxsync

Message:

IPRT/rest: Split up RTCRestBinaryString into a core RTCRestBinary type and two client side descenants for flexible handling of parameters and responses (still not tested). bugref:9167

Location:

trunk

Files:

• include/iprt/cpp/restbase.h (modified) (1 diff)
• include/iprt/cpp/restbinarystring.h (deleted)
• include/iprt/cpp/restclient.h (modified) (1 diff)
• src/VBox/Runtime/Makefile.kmk (modified) (1 diff)
• src/VBox/Runtime/common/rest/RTCRestBinaryString.cpp (deleted)
• src/VBox/Runtime/common/rest/rest-binary.cpp (added)

trunk/include/iprt/cpp/restbase.h

@@ -742 +742 @@
 };
 
+
+/**
+ * Class for handling binary blobs (strings).
+ *
+ * There are specializations of this class for body parameters and responses,
+ * see RTCRestBinaryParameter and RTCRestBinaryResponse.
+ */
+class RT_DECL_CLASS RTCRestBinary : public RTCRestObjectBase
+{
+public:
+    /** Default constructor. */
+    RTCRestBinary();
+    /** Destructor. */
+    virtual ~RTCRestBinary();
+
+    /** Safe copy assignment method. */
+    virtual int assignCopy(RTCRestBinary const &a_rThat);
+    /** Safe buffer copy method. */
+    virtual int assignCopy(void const *a_pvData, size_t a_cbData);
+
+    /** Use the specified data buffer directly. */
+    virtual int assignReadOnly(void const *a_pvData, size_t a_cbData);
+    /** Use the specified data buffer directly. */
+    virtual int assignWriteable(void *a_pvBuf, size_t a_cbBuf);
+    /** Frees the data held by the object and resets it default state. */
+    virtual void freeData();
+
+    /** Returns a pointer to the data blob. */
+    const uint8_t  *getPtr()  const { return m_pbData; }
+    /** Gets the size of the data. */
+    size_t          getSize() const { return m_cbData; }
+
+    /* Overridden methods: */
+    virtual int setNull(void) RT_OVERRIDE;
+    virtual int resetToDefault(void) RT_OVERRIDE;
+    virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
+    virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
+    virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
+    virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
+                           uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
+    virtual kTypeClass typeClass(void) const RT_OVERRIDE;
+    virtual const char *typeName(void) const RT_OVERRIDE;
+
+    /** Factory method. */
+    static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
+
+protected:
+    /** Pointer to data blob. */
+    uint8_t    *m_pbData;
+    /** Amount of valid data in the blob. */
+    size_t      m_cbData;
+    /** Number of bytes allocated for the m_pbData buffer. */
+    size_t      m_cbAllocated;
+    /** Set if the data is freeable, only ever clear if user data. */
+    bool        m_fFreeable;
+    /** Set if the data blob is readonly user provided data. */
+    bool        m_fReadOnly;
+
+private:
+    /* No copy constructor or copy assignment: */
+    RTCRestBinary(RTCRestBinary const &a_rThat);
+    RTCRestBinary &operator=(RTCRestBinary const &a_rThat);
+};
+
+
 /** @} */
 

trunk/include/iprt/cpp/restclient.h

@@ -35 +35 @@
  * @{
  */
+
+/**
+ * Specialization of RTCRestBinary for use with body parameters in a client.
+ *
+ * This enables registering data callbacks for provinding data to upload.
+ */
+class RT_DECL_CLASS RTCRestBinaryParameter : public RTCRestBinary
+{
+public:
+    /** Default constructor. */
+    RTCRestBinaryParameter();
+
+    /** Safe copy assignment method. */
+    virtual int assignCopy(RTCRestBinaryParameter const &a_rThat);
+    /** Safe copy assignment method.
+      * @note Resets callbacks and ASSUMES that @a a_cbData is the content length. */
+    virtual int assignCopy(RTCRestBinary const &a_rThat) RT_OVERRIDE;
+    /** Safe copy assignment method.
+     * @note Resets callbacks and ASSUMES that @a a_cbData is the content length. */
+    virtual int assignCopy(void const *a_pvData, size_t a_cbData) RT_OVERRIDE;
+
+    /**
+     * Use the specified data buffer directly.
+     * @note Resets callbacks and ASSUMES that @a a_cbData is the content length. */
+    virtual int assignReadOnly(void const *a_pvData, size_t a_cbData) RT_OVERRIDE;
+    /**
+     * Use the specified data buffer directly.
+     * @note This will assert and work like assignReadOnly. */
+    virtual int assignWriteable(void *a_pvBuf, size_t a_cbBuf) RT_OVERRIDE;
+
+    /* Overridden methods: */
+    virtual int resetToDefault() RT_OVERRIDE;
+    virtual const char *typeName(void) const RT_OVERRIDE;
+
+    /** Factory method. */
+    static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
+
+    /**
+     * Retrieves the callback data.
+     */
+    void *getCallbackData() const  { return m_pvCallbackData; }
+
+    /**
+     * Sets the content-type for an upload.
+     *
+     * @returns VINF_SUCCESS or VERR_NO_STR_MEMORY.
+     * @param   a_pszContentType    The content type to set.
+     *                              If NULL, no content type is set.
+     */
+    int setContentType(const char *a_pszContentType);
+
+    /**
+     * Gets the content type that was set.
+     */
+    RTCString const &getContentType() const { return m_strContentType; }
+
+    /**
+     * Callback for producing bytes to upload.
+     *
+     * @returns IPRT status code.
+     * @param   a_pThis         The related string object.
+     * @param   a_pvDst         Where to put the bytes.
+     * @param   a_cbDst         Max number of bytes to produce.
+     * @param   a_offContent    The byte offset corresponding to the start of @a a_pvDst.
+     * @param   a_pcbActual     Where to return the number of bytes actually produced.
+     * @remarks Use getCallbackData to get the user data.
+     */
+    typedef DECLCALLBACK(int) FNPRODUCER(RTCRestBinaryParameter *a_pThis, void *a_pvDst, size_t a_cbDst,
+                                         uint64_t a_offContent, size_t *a_pcbActual);
+    /** Pointer to a byte producer callback. */
+    typedef FNPRODUCER *PFNPRODUCER;
+
+    /**
+     * Sets the producer callback.
+     *
+     * @param   a_pfnProducer       The callback function for producing data.
+     * @param   a_pvCallbackData    Data the can be retrieved from the callback
+     *                              using getCallbackData().
+     * @param   a_cbContentLength   The amount of data that will be uploaded and
+     *                              to be set as the value of the content-length
+     *                              header field.  Pass UINT64_MAX if not known.
+     *
+     * @note    This will drop any buffer previously registered using setUploadData().
+     */
+    void setProducerCallback(PFNPRODUCER a_pfnProducer, void *a_pvCallbackData = NULL, uint64_t a_cbContentLength = UINT64_MAX);
+
+    /**
+     * Preprares transmission via the @a a_hHttp client instance.
+     *
+     * @returns IPRT status code.
+     * @param   a_hHttp             The HTTP client instance.
+     * @internal
+     */
+    virtual int xmitPrepare(RTHTTP a_hHttp) const;
+
+    /**
+     * For completing and/or undoing setup from xmitPrepare.
+     *
+     * @param   a_hHttp             The HTTP client instance.
+     * @internal
+     */
+    virtual void xmitComplete(RTHTTP a_hHttp) const;
+
+protected:
+    /** Number of bytes corresponding to content-length.
+     * UINT64_MAX if not known.  Used both for unploads and downloads. */
+    uint64_t    m_cbContentLength;
+    /** The content type if set (upload only). */
+    RTCString   m_strContentType;
+    /** Pointer to user-registered producer callback function (upload only). */
+    PFNPRODUCER m_pfnProducer;
+    /** User argument for both callbacks (both). */
+    void       *m_pvCallbackData;
+
+    /** Callback for use with RTHttpSetUploadCallback. */
+    static FNRTHTTPUPLOADCALLBACK   xmitHttpCallback;
+
+private:
+    /* No copy constructor or copy assignment: */
+    RTCRestBinaryParameter(RTCRestBinaryParameter const &a_rThat);
+    RTCRestBinaryParameter &operator=(RTCRestBinaryParameter const &a_rThat);
+};
+
+
+/**
+ * Specialization of RTCRestBinary for use with responses in a client.
+ *
+ * This enables registering data callbacks for consuming downloaded data.
+ */
+class RT_DECL_CLASS RTCRestBinaryResponse : public RTCRestBinary
+{
+public:
+    /** Default constructor. */
+    RTCRestBinaryResponse();
+
+    /** Safe copy assignment method. */
+    virtual int assignCopy(RTCRestBinaryResponse const &a_rThat);
+    /** Safe copy assignment method. */
+    virtual int assignCopy(RTCRestBinary const &a_rThat) RT_OVERRIDE;
+    /** Safe copy assignment method.
+     * @note This will assert and fail as it makes no sense for a download.  */
+    virtual int assignCopy(void const *a_pvData, size_t a_cbData) RT_OVERRIDE;
+
+    /**
+     * Use the specified data buffer directly.
+     * @note This will assert and fail as it makes no sense for a download.
+     */
+    virtual int assignReadOnly(void const *a_pvData, size_t a_cbData) RT_OVERRIDE;
+    /**
+     * Use the specified data buffer directly.
+     * @note This will drop any previously registered producer callback and user data.
+     */
+    virtual int assignWriteable(void *a_pvBuf, size_t a_cbBuf) RT_OVERRIDE;
+
+    /* Overridden methods: */
+    virtual int resetToDefault() RT_OVERRIDE;
+    virtual const char *typeName(void) const RT_OVERRIDE;
+
+    /** Factory method. */
+    static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
+
+    /**
+     * Retrieves the callback data.
+     */
+    void *getCallbackData() const  { return m_pvCallbackData; }
+
+    /**
+     * Sets the max size to download to memory.
+     *
+     * This also indicates the intention to download to a memory buffer, so it
+     * will drop any previously registered consumer callback and its user data.
+     *
+     * @param   a_cbMaxDownload Maximum number of bytes to download to memory.
+     *                          If 0, a default is selected (currently 32MiB for
+     *                          32-bit hosts and 128MiB for 64-bit).
+     */
+    void setMaxDownloadSize(size_t a_cbMaxDownload);
+
+    /**
+     * Gets the content-length value (UINT64_MAX if not available).
+     */
+    uint64_t getContentLength() const { return m_cbContentLength; }
+
+    /**
+     * Callback for consuming downloaded bytes.
+     *
+     * @returns IPRT status code.
+     * @param   a_pThis         The related string object.
+     * @param   a_pvSrc         Buffer containing the bytes.
+     * @param   a_cbSrc         The number of bytes in the buffer.
+     * @param   a_uHttpStatus   The HTTP status code.
+     * @param   a_offContent    The byte offset corresponding to the start of @a a_pvSrc.
+     * @param   a_cbContent     The content length field value, UINT64_MAX if not available.
+     * @remarks Use getCallbackData to get the user data.
+     */
+    typedef DECLCALLBACK(int) FNCONSUMER(RTCRestBinaryResponse *a_pThis, const void *a_pvSrc, size_t a_cbSrc,
+                                         uint32_t a_uHttpStatus, uint64_t a_offContent, uint64_t a_cbContent);
+    /** Pointer to a byte consumer callback. */
+    typedef FNCONSUMER *PFNCONSUMER;
+
+    /**
+     * Sets the consumer callback.
+     *
+     * @param   a_pfnConsumer       The callback function for consuming downloaded data.
+     *                              NULL if data should be stored in m_pbData (the default).
+     * @param   a_pvCallbackData    Data the can be retrieved from the callback
+     *                              using getCallbackData().
+     */
+    void setConsumerCallback(PFNCONSUMER a_pfnConsumer, void *a_pvCallbackData = NULL);
+
+    /**
+     * Preprares for receiving via the @a a_hHttp client instance.
+     *
+     * @returns IPRT status code.
+     * @param   a_hHttp             The HTTP client instance.
+     * @param   a_fCallbackFlags    The HTTP callback flags (status code spec).
+     * @internal
+     */
+    virtual int receivePrepare(RTHTTP a_hHttp, uint32_t a_fCallbackFlags);
+
+    /**
+     * For completing and/or undoing setup from receivePrepare.
+     *
+     * @param   a_hHttp             The HTTP client instance.
+     * @internal
+     */
+    virtual void receiveComplete(RTHTTP a_hHttp);
+
+protected:
+    /** Number of bytes corresponding to content-length.
+     * UINT64_MAX if not known.  Used both for unploads and downloads. */
+    uint64_t    m_cbContentLength;
+    /** Number of bytes downloaded thus far. */
+    uint64_t    m_cbDownloaded;
+    /** Pointer to user-registered consumer callback function (download only). */
+    PFNCONSUMER m_pfnConsumer;
+    /** User argument for both callbacks (both). */
+    void       *m_pvCallbackData;
+    /** Maximum data to download to memory (download only). */
+    size_t      m_cbMaxDownload;
+
+    /** Callback for use with RTHttpSetDownloadCallback. */
+    static FNRTHTTPDOWNLOADCALLBACK receiveHttpCallback;
+
+private:
+    /* No copy constructor or copy assignment: */
+    RTCRestBinaryResponse(RTCRestBinaryResponse const &a_rThat);
+    RTCRestBinaryResponse &operator=(RTCRestBinaryResponse const &a_rThat);
+};
+
 
 /**

trunk/src/VBox/Runtime/Makefile.kmk

@@ -1653 +1653 @@
         generic/http-curl.cpp \
         common/rest/rest-primary-object-types.cpp \
+        common/rest/rest-binary.cpp \
         common/rest/RTCRestAnyObject.cpp \
         common/rest/RTCRestArrayBase.cpp \
-        common/rest/RTCRestBinaryString.cpp \
         common/rest/RTCRestClientApiBase.cpp \
         common/rest/RTCRestClientApiBaseOci.cpp \