restclient.h@ 74181

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

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

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

Download in other formats: