restclient.h@ 74243

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

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

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

Download in other formats: