[Development] Need suggestion for a new API

Andre Somers andre at familiesomers.nl
Fri Jan 31 18:03:52 CET 2014


Mandeep Sandhu schreef op 31-1-2014 13:47:
> Hi All,
>
> I needed a suggestion on an API I'm adding to QNetworkAccessManager 
> and co.
>
> I'm adding a HTTP redirect feature to QNAM. It can be enabled at a 
> global (QNAM) level, or can be enabled/disabled on a per request 
> (QNetworkRequest) basis. The per-request setting, if set, overrides 
> the global one otherwise uses whatever is set in the global setting.
>
> The default value of the global setting is false, i.e don't follow 
> redirects.
>
> The QNAM setting can be a simple bool which defaults to 'false' if not 
> explicitly set by the user. However, the request level setting needs 3 
> states - true (follow redirects), false (don't follow) and unset (use 
> global setting).
>
> I was thinking I can have the request level setting as a 'pointer to a 
> bool' which is uninitialized (NULL) if a user does NOT explicitly set 
> the behaviour for the request or is initialized to whatever value is 
> passed (true/false). But this would mean allocating space for a 
> pointer etc, though I can manage it with a scoped pointer.
>
> Or else I could have an enum in the request class identifying these 3 
> states (I don't want to add an enum for such a simple thing).
>
> Any other suggestions on how this could be handled?
I don't think that using a pointer to a bool would be good API.

myRequest->setFollowRedirects(&true); // ok, clear enough, but a bit weird
myRequest->setFollowRedirects(&false); // ok, clear enough, but a bit weird
myRequest->setFollowRedirects(0); //what does this mean?
vs.
myRequest->setFollowRedirects(QNetworkAccessManager::UseGlobalSetting); 
//perfectly clear
myRequest->setFollowRedirects(QNetworkAccessManager::AlwaysFollow); // 
perfectly clear
myRequest->setFollowRedirects(QNetworkAccessManager::NeverFollow); 
//perfectly clear

myQNam->setFollowRedirects(QNetworkAccessManager::UseGlobalSetting); // 
undefined, should fail I guess

The enum way would be way clearer, and allows for extension later if 
needed. I would use the same enum at both levels, documenting that using 
the FollowGlobal value does not make sense at the QNAM level and perhaps 
using an assert on that one. Note that if you use an enum at the API 
surface, that does not mean you *have* to use the enum internally as 
well. Not that a pointer to a bool is smaller than an enum, but...

The enum solution would allow for something like this to be added:
myRequest->setFollowRedirects(QNetworkAccessManager::OnlyFollowWithinDomain); 
//if such a thing would make sense

André




More information about the Development mailing list