restclient.h@ 74334

Last change on this file since 74334 was 74250, checked in by vboxsync, 6 years ago
IRPT/rest,http: Use header callbacks for capturing header values in responses. Removed [P]FNCREATEINSTANCE as it isn't needed any more (and it didn't work like expected for RTCRestString). Some HTTP header callback updates. bugref:9167
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 28.1 KB

Line
1	/** @file
2	* IPRT - C++ Representational State Transfer (REST) Client Classes.
3	*/
4
5	/*
6	* Copyright (C) 2008-2018 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___iprt_cpp_restclient_h
27	#define ___iprt_cpp_restclient_h
28
29	#include <iprt/http.h>
30	#include <iprt/cpp/restbase.h>
31	#include <iprt/cpp/reststringmap.h>
32
33
34	/** @defgroup grp_rt_cpp_restclient C++ Representational State Transfer (REST) Client Classes.
35	* @ingroup grp_rt_cpp
36	* @{
37	*/
38
39	/**
40	* Specialization of RTCRestBinary for use with body parameters in a client.
41	*
42	* This enables registering data callbacks for provinding data to upload.
43	*/
44	class RT_DECL_CLASS RTCRestBinaryParameter : public RTCRestBinary
45	{
46	public:
47	/** Default constructor. */
48	RTCRestBinaryParameter();
49
50	/** Safe copy assignment method. */
51	virtual int assignCopy(RTCRestBinaryParameter const &a_rThat);
52	/** Safe copy assignment method.
53	* @note Resets callbacks and ASSUMES that @a a_cbData is the content length. */
54	virtual int assignCopy(RTCRestBinary const &a_rThat) RT_OVERRIDE;
55	/** Safe copy assignment method.
56	* @note Resets callbacks and ASSUMES that @a a_cbData is the content length. */
57	virtual int assignCopy(void const *a_pvData, size_t a_cbData) RT_OVERRIDE;
58
59	/**
60	* Use the specified data buffer directly.
61	* @note Resets callbacks and ASSUMES that @a a_cbData is the content length. */
62	virtual int assignReadOnly(void const *a_pvData, size_t a_cbData) RT_OVERRIDE;
63	/**
64	* Use the specified data buffer directly.
65	* @note This will assert and work like assignReadOnly. */
66	virtual int assignWriteable(void *a_pvBuf, size_t a_cbBuf) RT_OVERRIDE;
67
68	/* Overridden methods: */
69	virtual int resetToDefault() RT_OVERRIDE;
70	virtual const char *typeName(void) const RT_OVERRIDE;
71
72	/** Factory method. */
73	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
74
75	/**
76	* Retrieves the callback data.
77	*/
78	inline void *getCallbackData() const { return m_pvCallbackData; }
79
80	/**
81	* Sets the content-type for an upload.
82	*
83	* @returns VINF_SUCCESS or VERR_NO_STR_MEMORY.
84	* @param a_pszContentType The content type to set.
85	* If NULL, no content type is set.
86	*/
87	int setContentType(const char *a_pszContentType);
88
89	/**
90	* Gets the content type that was set.
91	*/
92	inline RTCString const &getContentType() const { return m_strContentType; }
93
94	/**
95	* Gets the content-length value (UINT64_MAX if not available).
96	*/
97	inline uint64_t getContentLength() const { return m_cbContentLength; }
98
99	/**
100	* Callback for producing bytes to upload.
101	*
102	* @returns IPRT status code.
103	* @param a_pThis The related string object.
104	* @param a_pvDst Where to put the bytes.
105	* @param a_cbDst Max number of bytes to produce.
106	* @param a_offContent The byte offset corresponding to the start of @a a_pvDst.
107	* @param a_pcbActual Where to return the number of bytes actually produced.
108	*
109	* @remarks Use getCallbackData to get the user data.
110	*
111	* @note The @a a_offContent parameter does not imply random access or anthing
112	* like that, it is just a convenience provided by the caller. The value
113	* is the sum of the previously returned @a *pcbActual values.
114	*/
115	typedef DECLCALLBACK(int) FNPRODUCER(RTCRestBinaryParameter a_pThis, void a_pvDst, size_t a_cbDst,
116	uint64_t a_offContent, size_t *a_pcbActual);
117	/** Pointer to a byte producer callback. */
118	typedef FNPRODUCER *PFNPRODUCER;
119
120	/**
121	* Sets the producer callback.
122	*
123	* @param a_pfnProducer The callback function for producing data.
124	* @param a_pvCallbackData Data the can be retrieved from the callback
125	* using getCallbackData().
126	* @param a_cbContentLength The amount of data that will be uploaded and
127	* to be set as the value of the content-length
128	* header field. Pass UINT64_MAX if not known.
129	*
130	* @note This will drop any buffer previously registered using setUploadData().
131	*/
132	void setProducerCallback(PFNPRODUCER a_pfnProducer, void *a_pvCallbackData = NULL, uint64_t a_cbContentLength = UINT64_MAX);
133
134	/**
135	* Preprares transmission via the @a a_hHttp client instance.
136	*
137	* @returns IPRT status code.
138	* @param a_hHttp The HTTP client instance.
139	* @internal
140	*/
141	virtual int xmitPrepare(RTHTTP a_hHttp) const;
142
143	/**
144	* For completing and/or undoing setup from xmitPrepare.
145	*
146	* @param a_hHttp The HTTP client instance.
147	* @internal
148	*/
149	virtual void xmitComplete(RTHTTP a_hHttp) const;
150
151	protected:
152	/** Number of bytes corresponding to content-length.
153	* UINT64_MAX if not known. Used both for unploads and downloads. */
154	uint64_t m_cbContentLength;
155	/** The content type if set (upload only). */
156	RTCString m_strContentType;
157	/** Pointer to user-registered producer callback function (upload only). */
158	PFNPRODUCER m_pfnProducer;
159	/** User argument for both callbacks (both). */
160	void *m_pvCallbackData;
161
162	/** Callback for use with RTHttpSetUploadCallback. */
163	static FNRTHTTPUPLOADCALLBACK xmitHttpCallback;
164
165	private:
166	/* No copy constructor or copy assignment: */
167	RTCRestBinaryParameter(RTCRestBinaryParameter const &a_rThat);
168	RTCRestBinaryParameter &operator=(RTCRestBinaryParameter const &a_rThat);
169	};
170
171
172	/**
173	* Specialization of RTCRestBinary for use with responses in a client.
174	*
175	* This enables registering data callbacks for consuming downloaded data.
176	*/
177	class RT_DECL_CLASS RTCRestBinaryResponse : public RTCRestBinary
178	{
179	public:
180	/** Default constructor. */
181	RTCRestBinaryResponse();
182
183	/** Safe copy assignment method. */
184	virtual int assignCopy(RTCRestBinaryResponse const &a_rThat);
185	/** Safe copy assignment method. */
186	virtual int assignCopy(RTCRestBinary const &a_rThat) RT_OVERRIDE;
187	/** Safe copy assignment method.
188	* @note This will assert and fail as it makes no sense for a download. */
189	virtual int assignCopy(void const *a_pvData, size_t a_cbData) RT_OVERRIDE;
190
191	/**
192	* Use the specified data buffer directly.
193	* @note This will assert and fail as it makes no sense for a download.
194	*/
195	virtual int assignReadOnly(void const *a_pvData, size_t a_cbData) RT_OVERRIDE;
196	/**
197	* Use the specified data buffer directly.
198	* @note This will drop any previously registered producer callback and user data.
199	*/
200	virtual int assignWriteable(void *a_pvBuf, size_t a_cbBuf) RT_OVERRIDE;
201
202	/* Overridden methods: */
203	virtual int resetToDefault() RT_OVERRIDE;
204	virtual const char *typeName(void) const RT_OVERRIDE;
205
206	/** Factory method. */
207	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
208
209	/**
210	* Retrieves the callback data.
211	*/
212	inline void *getCallbackData() const { return m_pvCallbackData; }
213
214	/**
215	* Sets the max size to download to memory.
216	*
217	* This also indicates the intention to download to a memory buffer, so it
218	* will drop any previously registered consumer callback and its user data.
219	*
220	* @param a_cbMaxDownload Maximum number of bytes to download to memory.
221	* If 0, a default is selected (currently 32MiB for
222	* 32-bit hosts and 128MiB for 64-bit).
223	*/
224	void setMaxDownloadSize(size_t a_cbMaxDownload);
225
226	/**
227	* Gets the content-length value (UINT64_MAX if not available).
228	*/
229	inline uint64_t getContentLength() const { return m_cbContentLength; }
230
231	/**
232	* Callback for consuming downloaded bytes.
233	*
234	* @returns IPRT status code.
235	* @param a_pThis The related string object.
236	* @param a_pvSrc Buffer containing the bytes.
237	* @param a_cbSrc The number of bytes in the buffer.
238	* @param a_uHttpStatus The HTTP status code.
239	* @param a_offContent The byte offset corresponding to the start of @a a_pvSrc.
240	* @param a_cbContent The content length field value, UINT64_MAX if not available.
241	*
242	* @remarks Use getCallbackData to get the user data.
243	*
244	* @note The @a a_offContent parameter does not imply random access or anthing
245	* like that, it is just a convenience provided by the caller. The value
246	* is the sum of the previous @a a_cbSrc values.
247	*/
248	typedef DECLCALLBACK(int) FNCONSUMER(RTCRestBinaryResponse a_pThis, const void a_pvSrc, size_t a_cbSrc,
249	uint32_t a_uHttpStatus, uint64_t a_offContent, uint64_t a_cbContent);
250	/** Pointer to a byte consumer callback. */
251	typedef FNCONSUMER *PFNCONSUMER;
252
253	/**
254	* Sets the consumer callback.
255	*
256	* @param a_pfnConsumer The callback function for consuming downloaded data.
257	* NULL if data should be stored in m_pbData (the default).
258	* @param a_pvCallbackData Data the can be retrieved from the callback
259	* using getCallbackData().
260	*/
261	void setConsumerCallback(PFNCONSUMER a_pfnConsumer, void *a_pvCallbackData = NULL);
262
263	/**
264	* Preprares for receiving via the @a a_hHttp client instance.
265	*
266	* @returns IPRT status code.
267	* @param a_hHttp The HTTP client instance.
268	* @param a_fCallbackFlags The HTTP callback flags (status code spec).
269	* @internal
270	*/
271	virtual int receivePrepare(RTHTTP a_hHttp, uint32_t a_fCallbackFlags);
272
273	/**
274	* For completing and/or undoing setup from receivePrepare.
275	*
276	* @param a_hHttp The HTTP client instance.
277	* @internal
278	*/
279	virtual void receiveComplete(RTHTTP a_hHttp);
280
281	protected:
282	/** Number of bytes corresponding to content-length.
283	* UINT64_MAX if not known. Used both for unploads and downloads. */
284	uint64_t m_cbContentLength;
285	/** Number of bytes downloaded thus far. */
286	uint64_t m_cbDownloaded;
287	/** Pointer to user-registered consumer callback function (download only). */
288	PFNCONSUMER m_pfnConsumer;
289	/** User argument for both callbacks (both). */
290	void *m_pvCallbackData;
291	/** Maximum data to download to memory (download only). */
292	size_t m_cbMaxDownload;
293
294	/** Callback for use with RTHttpSetDownloadCallback. */
295	static FNRTHTTPDOWNLOADCALLBACK receiveHttpCallback;
296
297	private:
298	/* No copy constructor or copy assignment: */
299	RTCRestBinaryResponse(RTCRestBinaryResponse const &a_rThat);
300	RTCRestBinaryResponse &operator=(RTCRestBinaryResponse const &a_rThat);
301	};
302
303
304	/**
305	* Base class for REST client requests.
306	*
307	* This encapsulates parameters and helps transform them into a HTTP request.
308	*
309	* Parameters can be transfered in a number of places:
310	* - Path part of the URL.
311	* - Query part of the URL.
312	* - HTTP header fields.
313	* - FORM body.
314	* - JSON body.
315	* - XML body.
316	* - ...
317	*
318	* They can be require or optional. The latter may have default values. In
319	* swagger 3 they can also be nullable, which means the null-indicator cannot
320	* be used for tracking optional parameters.
321	*/
322	class RT_DECL_CLASS RTCRestClientRequestBase
323	{
324	public:
325	RTCRestClientRequestBase();
326	virtual ~RTCRestClientRequestBase();
327	RTCRestClientRequestBase(RTCRestClientRequestBase const &a_rThat);
328	RTCRestClientRequestBase &operator=(RTCRestClientRequestBase const &a_rThat);
329
330	/**
331	* Reset all members to default values.
332	* @returns IPRT status code.
333	*/
334	virtual int resetToDefault() = 0;
335
336	/**
337	* Prepares the HTTP handle for transmitting this request.
338	*
339	* @returns IPRT status code.
340	* @param a_pStrPath Where to set path parameters. Will be appended to the base path.
341	* @param a_pStrQuery Where to set query parameters.
342	* @param a_hHttp Where to set header parameters and such.
343	* @param a_pStrBody Where to set body parameters.
344	*/
345	virtual int xmitPrepare(RTCString a_pStrPath, RTCString a_pStrQuery, RTHTTP a_hHttp, RTCString *a_pStrBody) const = 0;
346
347	/**
348	* Always called after the request has been transmitted.
349	*
350	* @param a_rcStatus Negative numbers are IPRT errors, positive are HTTP status codes.
351	* @param a_hHttp The HTTP handle the request was performed on.
352	*/
353	virtual void xmitComplete(int a_rcStatus, RTHTTP a_hHttp) const = 0;
354
355	/**
356	* Checks if there are were any assignment errors.
357	*/
358	inline bool hasAssignmentErrors() const { return m_fErrorSet != 0; }
359
360	protected:
361	/** Set of fields that have been explicitly assigned a value. */
362	uint64_t m_fIsSet;
363	/** Set of fields where value assigning failed. */
364	uint64_t m_fErrorSet;
365
366	/** Path parameter descriptor. */
367	typedef struct
368	{
369	const char pszName; /< The name string to replace (including {}). /
370	size_t cchName; /*< Length of pszName. /
371	uint32_t fFlags; /*< The toString flags. /
372	uint8_t iBitNo; /*< The parameter bit number. /
373	} PATHPARAMDESC;
374
375	/** Path parameter state. */
376	typedef struct
377	{
378	RTCRestObjectBase const pObj; /< Pointer to the parameter object. /
379	size_t offName; /*< Maintained by worker. /
380	} PATHPARAMSTATE;
381
382	/**
383	* Do path parameters.
384	*
385	* @returns IPRT status code
386	* @param a_pStrPath The destination path.
387	* @param a_pszPathTemplate The path template string.
388	* @param a_cchPathTemplate The length of the path template string.
389	* @param a_paPathParams The path parameter descriptors (static).
390	* @param a_paPathParamStates The path parameter objects and states.
391	* @param a_cPathParams Number of path parameters.
392	*/
393	int doPathParameters(RTCString a_pStrPath, const char a_pszPathTemplate, size_t a_cchPathTemplate,
394	PATHPARAMDESC const a_paPathParams, PATHPARAMSTATE a_paPathParamStates, size_t a_cPathParams) const;
395
396	/** Query parameter descriptor. */
397	typedef struct
398	{
399	const char pszName; /< The parameter name. /
400	uint32_t fFlags; /*< The toString flags. /
401	bool fRequired; /*< Required or not. /
402	uint8_t iBitNo; /*< The parameter bit number. /
403	} QUERYPARAMDESC;
404
405	/**
406	* Do query parameters.
407	*
408	* @returns IPRT status code
409	* @param a_pStrQuery The destination string.
410	* @param a_paQueryParams The query parameter descriptors.
411	* @param a_papQueryParamObjs The query parameter objects, parallel to @a a_paQueryParams.
412	* @param a_cQueryParams Number of query parameters.
413	*/
414	int doQueryParameters(RTCString a_pStrQuery, QUERYPARAMDESC const a_paQueryParams,
415	RTCRestObjectBase const **a_papQueryParamObjs, size_t a_cQueryParams) const;
416
417	/** Header parameter descriptor. */
418	typedef struct
419	{
420	const char pszName; /< The parameter name. /
421	uint32_t fFlags; /*< The toString flags. /
422	bool fRequired; /*< Required or not. /
423	uint8_t iBitNo; /*< The parameter bit number. /
424	bool fMapCollection; /*< Collect headers starting with pszName into a map. /
425	} HEADERPARAMDESC;
426
427	/**
428	* Do header parameters.
429	*
430	* @returns IPRT status code
431	* @param a_hHttp Where to set header parameters.
432	* @param a_paHeaderParams The header parameter descriptors.
433	* @param a_papHeaderParamObjs The header parameter objects, parallel to @a a_paHeaderParams.
434	* @param a_cHeaderParams Number of header parameters.
435	*/
436	int doHeaderParameters(RTHTTP a_hHttp, HEADERPARAMDESC const *a_paHeaderParams,
437	RTCRestObjectBase const **a_papHeaderParamObjs, size_t a_cHeaderParams) const;
438	};
439
440
441	/**
442	* Base class for REST client responses.
443	*/
444	class RT_DECL_CLASS RTCRestClientResponseBase
445	{
446	public:
447	/** Default constructor. */
448	RTCRestClientResponseBase();
449	/** Destructor. */
450	virtual ~RTCRestClientResponseBase();
451	/** Copy constructor. */
452	RTCRestClientResponseBase(RTCRestClientResponseBase const &a_rThat);
453	/** Copy assignment operator. */
454	RTCRestClientResponseBase &operator=(RTCRestClientResponseBase const &a_rThat);
455
456	/**
457	* Resets the object state.
458	*/
459	virtual void reset(void);
460
461	/**
462	* Prepares the HTTP handle for receiving the response.
463	*
464	* This may install callbacks and such like.
465	*
466	* When overridden, the parent class must always be called.
467	*
468	* @returns IPRT status code.
469	* @param a_hHttp The HTTP handle to prepare for receiving.
470	*/
471	virtual int receivePrepare(RTHTTP a_hHttp);
472
473	/**
474	* Called when the HTTP request has been completely received.
475	*
476	* @param a_rcStatus Negative numbers are IPRT errors, positive are HTTP status codes.
477	* @param a_hHttp The HTTP handle the request was performed on.
478	* This can be NIL_RTHTTP should something fail early, in
479	* which case it is possible receivePrepare() wasn't called.
480	*
481	* @note Called before consumeBody() but after consumeHeader().
482	*/
483	virtual void receiveComplete(int a_rcStatus, RTHTTP a_hHttp);
484
485	/**
486	* Callback that consumes HTTP body data from the server.
487	*
488	* @param a_pchData Body data.
489	* @param a_cbData Amount of body data.
490	*
491	* @note Called after consumeHeader().
492	*/
493	virtual void consumeBody(const char *a_pchData, size_t a_cbData);
494
495	/**
496	* Called after status, headers and body all have been presented.
497	*
498	* @returns IPRT status code.
499	*/
500	virtual void receiveFinal();
501
502	/**
503	* Getter for m_rcStatus.
504	* @returns Negative numbers are IPRT errors, positive are HTTP status codes.
505	*/
506	inline int getStatus() { return m_rcStatus; }
507
508	/**
509	* Getter for m_rcHttp.
510	* @returns HTTP status code or VERR_NOT_AVAILABLE.
511	*/
512	inline int getHttpStatus() { return m_rcHttp; }
513
514	/**
515	* Getter for m_pErrInfo.
516	*/
517	inline PCRTERRINFO getErrInfo(void) const { return m_pErrInfo; }
518
519	/**
520	* Getter for m_strContentType.
521	*/
522	inline RTCString const &getContentType(void) const { return m_strContentType; }
523
524
525	protected:
526	/** Negative numbers are IPRT errors, positive are HTTP status codes. */
527	int m_rcStatus;
528	/** The HTTP status code, VERR_NOT_AVAILABLE if not set. */
529	int m_rcHttp;
530	/** Error information. */
531	PRTERRINFO m_pErrInfo;
532	/** The value of the Content-Type header field. */
533	RTCString m_strContentType;
534
535	PRTERRINFO getErrInfoInternal(void);
536	void deleteErrInfo(void);
537	void copyErrInfo(PCRTERRINFO pErrInfo);
538
539	/**
540	* Reports an error (or warning if a_rc non-negative).
541	*
542	* @returns a_rc
543	* @param a_rc The status code to report and return. The first
544	* error status is assigned to m_rcStatus, subsequent
545	* ones as well as informational statuses are not
546	* recorded by m_rcStatus.
547	* @param a_pszFormat The message format string.
548	* @param ... Message arguments.
549	*/
550	int addError(int a_rc, const char *a_pszFormat, ...);
551
552	/**
553	* Deserializes a header field value.
554	*
555	* @returns IPRT status code.
556	* @param a_pObj The object to deserialize into.
557	* @param a_pchValue Pointer to the value (not zero terminated).
558	* Not necessarily valid UTF-8!
559	* @param a_cchValue The value length.
560	* @param a_fFlags Flags to pass to fromString().
561	* @param a_pszErrorTag The error tag (field name).
562	*/
563	int deserializeHeader(RTCRestObjectBase a_pObj, const char a_pchValue, size_t a_cchValue,
564	uint32_t a_fFlags, const char *a_pszErrorTag);
565
566	/**
567	* Deserializes a header field value.
568	*
569	* @returns IPRT status code.
570	* @param a_pMap The string map object to deserialize into.
571	* @param a_pchField Pointer to the map field name. (Caller dropped the prefix.)
572	* Not necessarily valid UTF-8!
573	* @param a_cchField Length of field name.
574	* @param a_pchValue Pointer to the value (not zero terminated).
575	* Not necessarily valid UTF-8!
576	* @param a_cchValue The value length.
577	* @param a_fFlags Flags to pass to fromString().
578	* @param a_pszErrorTag The error tag (field name).
579	*/
580	int deserializeHeaderIntoMap(RTCRestStringMapBase a_pMap, const char a_pchField, size_t a_cchField,
581	const char a_pchValue, size_t a_cchValue, uint32_t a_fFlags, const char a_pszErrorTag);
582
583	/**
584	* Helper that does the deserializing of the response body.
585	*
586	* @param a_pDst The destination object for the body content.
587	* @param a_pchData The body blob.
588	* @param a_cbData The size of the body blob.
589	*/
590	void deserializeBody(RTCRestObjectBase a_pDst, const char a_pchData, size_t a_cbData);
591
592	/**
593	* Primary json cursor for parsing bodies.
594	*/
595	class PrimaryJsonCursorForBody : public RTCRestJsonPrimaryCursor
596	{
597	public:
598	RTCRestClientResponseBase m_pThat; /< Pointer to response object. /
599	PrimaryJsonCursorForBody(RTJSONVAL hValue, const char pszName, RTCRestClientResponseBase a_pThat);
600	virtual int addError(RTCRestJsonCursor const &a_rCursor, int a_rc, const char *a_pszFormat, ...) RT_OVERRIDE;
601	virtual int unknownField(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
602	};
603
604
605	/**
606	* Consumes a header.
607	*
608	* Child classes can override this to pick up their header fields, but must
609	* always call the parent class.
610	*
611	* @returns IPRT status code.
612	* @param a_uMatchWord Match word constructed by RTHTTP_MAKE_HDR_MATCH_WORD
613	* @param a_pchField The field name (not zero terminated).
614	* Not necessarily valid UTF-8!
615	* @param a_cchField The length of the field.
616	* @param a_pchValue The field value (not zero terminated).
617	* @param a_cchValue The length of the value.
618	*/
619	virtual int consumeHeader(uint32_t a_uMatchWord, const char *a_pchField, size_t a_cchField,
620	const char *a_pchValue, size_t a_cchValue);
621
622	private:
623	/** Callback for use with RTHttpSetHeaderCallback. */
624	static FNRTHTTPHEADERCALLBACK receiveHttpHeaderCallback;
625	};
626
627
628	/**
629	* Base class for REST client responses.
630	*/
631	class RT_DECL_CLASS RTCRestClientApiBase
632	{
633	public:
634	RTCRestClientApiBase()
635	: m_hHttp(NIL_RTHTTP)
636	{}
637	virtual ~RTCRestClientApiBase();
638
639	/** @name Base path (URL) handling.
640	* @{ */
641	/**
642	* Gets the base path we're using.
643	*
644	* @returns Base URL string. If empty, we'll be using the default one.
645	*/
646	inline RTCString const &getBasePath(void) const
647	{
648	return m_strBasePath;
649	}
650
651	/**
652	* Sets the base path (URL) to use when talking to the server.
653	*
654	* Setting the base path is only required if there is a desire to use a
655	* different server from the one specified in the API specification, like
656	* for instance regional one.
657	*
658	* @param a_pszPath The base path to use.
659	*/
660	virtual void setBasePath(const char *a_pszPath)
661	{
662	m_strBasePath = a_pszPath;
663	}
664
665	/**
666	* Sets the base path (URL) to use when talking to the server.
667	*
668	* Setting the base path is only required if there is a desire to use a
669	* different server from the one specified in the API specification, like
670	* for instance regional one.
671	*
672	* @param a_strPath The base path to use.
673	* @note Defers to the C-string variant.
674	*/
675	inline void setBasePath(RTCString const &a_strPath) { setBasePath(a_strPath.c_str()); }
676
677	/**
678	* Gets the default base path (URL) as specified in the specs.
679	*
680	* @returns Base path (URL) string.
681	*/
682	virtual const char *getDefaultBasePath() = 0;
683	/** @} */
684
685	/** Flags to doCall. */
686	enum
687	{
688	kDoCall_OciReqSignExcludeBody = 1 /*< Exclude the body when doing OCI request signing. /
689	};
690
691	protected:
692	/** Handle to the HTTP connection object. */
693	RTHTTP m_hHttp;
694	/** The base path to use. */
695	RTCString m_strBasePath;
696
697	/* Make non-copyable (RTCNonCopyable causes warnings): */
698	RTCRestClientApiBase(RTCRestOutputToString const &);
699	RTCRestClientApiBase *operator=(RTCRestOutputToString const &);
700
701	/**
702	* Re-initializes the HTTP instance.
703	*
704	* @returns IPRT status code.
705	*/
706	virtual int reinitHttpInstance();
707
708	/**
709	* Hook that's called when doCall has fully assembled the request.
710	*
711	* Can be used for request signing and similar final steps.
712	*
713	* @returns IPRT status code.
714	* @param a_hHttp The HTTP client instance.
715	* @param a_rStrFullUrl The full URL.
716	* @param a_enmHttpMethod The HTTP request method.
717	* @param a_rStrXmitBody The body text.
718	* @param a_fFlags kDoCall_XXX.
719	*/
720	virtual int xmitReady(RTHTTP a_hHttp, RTCString const &a_rStrFullUrl, RTHTTPMETHOD a_enmHttpMethod,
721	RTCString const &a_rStrXmitBody, uint32_t a_fFlags);
722
723	/**
724	* Implements stuff for making an API call.
725	*
726	* @returns a_pResponse->getStatus()
727	* @param a_rRequest Reference to the request object.
728	* @param a_enmHttpMethod The HTTP request method.
729	* @param a_pResponse Pointer to the response object.
730	* @param a_pszMethod The method name, for logging purposes.
731	* @param a_fFlags kDoCall_XXX.
732	*/
733	virtual int doCall(RTCRestClientRequestBase const &a_rRequest, RTHTTPMETHOD a_enmHttpMethod,
734	RTCRestClientResponseBase a_pResponse, const char a_pszMethod, uint32_t a_fFlags);
735
736	/**
737	* Implements OCI style request signing.
738	*
739	* @returns IPRT status code.
740	* @param a_hHttp The HTTP client instance.
741	* @param a_rStrFullUrl The full URL.
742	* @param a_enmHttpMethod The HTTP request method.
743	* @param a_rStrXmitBody The body text.
744	* @param a_fFlags kDoCall_XXX.
745	* @param a_hKey The key to use for signing.
746	* @param a_rStrKeyId The key ID.
747	*
748	* @remarks The signing scheme is covered by a series of drafts RFC, the latest being:
749	* https://tools.ietf.org/html/draft-cavage-http-signatures-10
750	*/
751	int ociSignRequest(RTHTTP a_hHttp, RTCString const &a_rStrFullUrl, RTHTTPMETHOD a_enmHttpMethod,
752	RTCString const &a_rStrXmitBody, uint32_t a_fFlags, RTCRKEY a_hKey, RTCString const &a_rStrKeyId);
753	};
754
755	/** @} */
756
757	#endif
758

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/cpp/restclient.h@ 74334

Download in other formats: