My opinion: the presence or absence of APIs should not depend on #defines.

For example, I would consider any APIs whose presence, absence, or signature is 
affected by
#ifdef __WITH_TLS__
to be a bug that needs to be fixed.

-----Original Message-----
From: Mats Wichmann [mailto:m...@wichmann.us] 
Sent: Thursday, February 22, 2018 2:06 PM
To: Dave Thaler <dtha...@microsoft.com>; Wouter van der Beek (wovander) 
<wovan...@cisco.com>; Nash, George <george.n...@intel.com>; 
iotivity-dev@lists.iotivity.org
Subject: Re: [dev] clear distinction of what is below and above the APIs

On 02/22/2018 12:15 PM, Dave Thaler wrote:
>
> The API can evolve, just like OCF specs, evolve so there's no fixed 
> definition per se.

Of course it's not fixed over time, but for any given release there should be a 
well-known API. Then the next release there will be another well known API, 
such that we can generate a document which lists the difference between, say, 
1.3's API and 1.4's API.  What is that definition?

It's not what is listed at 
https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.iotivity.org%2Fdocumentation&data=04%7C01%7Cdthaler%40microsoft.com%7Cf2aa9c7e08a143383a9e08d57a408597%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C1%7C636549339899693878%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwifQ%3D%3D%7C-1&sdata=Lmb4GJ3VC3XDMnPwwUJszTqjfhjfdAwyA1vzMagq3as%3D&reserved=0,
because some header portions are omitted by the documentation build as they're 
bracketed in #if sections, even though those portions are enabled by default in 
a code build.  Until very recently, the documentation build expanded no defines 
at all, now it defines (only) the ones related to deprecation.

In particular, security things are left out of the online definition.
You get left with questions like - Are these part of the API or not?

#ifdef __WITH_TLS__
bool OC_CALL OCRepPayloadSetPropPubDataType(OCRepPayload *payload, const char 
*name, const OicSecKey_t *value); bool OC_CALL 
OCRepPayloadSetPropPubDataTypeAsOwner(OCRepPayload
*payload, const char *name, const OicSecKey_t *value); bool OC_CALL 
OCRepPayloadGetPropPubDataType(const OCRepPayload *payload, const char *name, 
OicSecKey_t *value); #endif

Is "it depends on how the stack was compiled" really a good answer?
(not to mention that the docs will not list those three at all)

_______________________________________________
iotivity-dev mailing list
iotivity-dev@lists.iotivity.org
https://lists.iotivity.org/mailman/listinfo/iotivity-dev

Reply via email to