It?s all proprietary, so I can?t share specific code.
But yes our C-SDK methods are all carefully documented. I?m just maintaining
the .NET piece of it, and aren?t the real architect behind it all, so I don?t
understand all the inner workings of it. It can be brittle though. If you get
your doxygen markups wrong, the C-SDK might compile, but you could break the
generated code.
The doxygen comments would generally state which classes they are a member of,
which platforms it should be included in (some members are sometimes needed
internally to support specific platforms), inheritance, visibility (protected,
internal, public etc), whether it?s a constructor, property or method etc.
It?s all turned into a big XML document, and each code-generator then uses that
to generate code.
For example you could change this C-SDK member:
/**
* This function gets the byte string from the payload.
*
* @param payload Pointer to the payload from which byte string needs to be
retrieved.
* @param name Name of the byte string.
* @param value Byte string and it's length.
*
* @note: Caller needs to invoke OCFree on value.bytes after it is finished
using the byte string.
*
* @return true on success, false upon failure.
*/
bool OCRepPayloadGetPropByteString(const OCRepPayload* payload, const char*
name, OCByteString* value);
to this:
/**
* This function gets the byte string from the payload.
*
* @param [in] payload Pointer to the payload from which byte string needs
to be retrieved.
* @param [in] name Name of the byte string.
* @param [out] value Byte string and it's length.
*
* @note: Caller needs to invoke OCFree on value.bytes after it is finished
using the byte string.
*
* @return true on success, false upon failure.
* \public \memberof OCRepPayload
* \method
*/
bool OCRepPayloadGetPropByteString(const OCRepPayload* payload, const char*
name, OCByteString* value);
This should be enough to know that you need to create a class called
OCRepPayload, and it should have a method called GetPropByteString (you
auto-remove the class-name prefix). From the OCRepPayload pointer definition
you should also be able to infer that it inherits from OCPayload.
For instance the .NET generator might be able to generate this class from this
doc and method signature:
public class OCRepPayload : OCPayload
{
private IntPtr ocpayload;
public OCByteString GetPropByteString(string name)
{
OCByteString result = null;
If(OCRepPayloadGetPropByteString(handle, name, out result))
return result;
throw new ArgumentException(nameof(name));
}
[DllImport("octbstack.dll?, CallingConvention = CallingConvention.Cdecl)]
private static extern bool OCRepPayloadGetPropByteString (IntPtr payload,
[MarshalAs(UnmanagedType.LPStr)] string name, out OCByteString value);
}
One of our big differences between the Iotivity SDK is that we _always_ return
true/false. False means an error happened, and we have a method for getting
last known error and then throwing that in the higher-level SDK. This also
allows us to throw very detailed errors messages with native stacks etc.
In the Iotivity SDK there?s a combination of returning the value as a result,
returning true/false for success (as above), or return OCStackResult. It would
probably require some additional markup for the code-generator to understand
these differences and generate the appropriate code. I don?t see why this
couldn?t be achieved, but it would require significant effort on beefing up the
C-SDK documentation ? lots of methods doesn?t even have any documentation, and
the stuff that is there, needs more metadata to better understand the
parameters and results. That however would benefit the generated doc anyway.
To put it another way: Documentation first before this approach is remotely
feasible. However I definitely support this idea, as I?m currently
hand-building the above .NET code, and it?s very tedious, time consuming and
error prone. It?s also near-impossible to keep it in sync with any new methods
being added. I can only imagine the C++, Android and iOS SDKs are experiencing
the same challenges?
/Morten
From: Gregg Reynolds<mailto:[email protected]>
Sent: Wednesday, January 11, 2017 12:15 PM
To: Morten Nielsen<mailto:mn at iter.dk>
Cc: iotivity-dev at lists.iotivity.org<mailto:iotivity-dev at
lists.iotivity.org>; Thiago Macieira<mailto:thiago.macieira at intel.com>
Subject: RE: [dev] Integer representation in OCRepresentation, OCRepPayload and
cbor encoder
On Jan 11, 2017 2:04 PM, "Morten Nielsen" <mn at iter.dk<mailto:mn at iter.dk>>
wrote:
This idea might be valuable or not, but in my day-to-day work we also have a
C-SDK, and all its public methods are heavily documented and tagged.
We then use a combination of Doxygen and Python scripts to auto-generate
higher-level OO classes for use by Objective C, Android/Java, .NET and QT/C++.
This has worked really well for us across all the platforms once these scripts
were solidified.
It ensures all platforms have the same API, but the code-generator can adapt
and tweak the APIs to make them feel/look more native to the platform.
This was naturally a big investment setting up, but it has paid itself back
many times over since. It also means adding another language/platform was very
easy, as it was mainly just a matter of updating the code-generator. We also
don?t even have to worry about the higher-level classes getting out of sync
with the C-SDK.
I hereby authorize you to make this happen here! ;)
doxygen: +1. the rest sounds good, but how do you go from c to oo? you must
have organized your c code very carefully with that in mind, no? can you share
any code?
gregg
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170111/017a1fed/attachment.html>
