docs(azure-iot-device): setOptions documentation #865
Conversation
doc/device_client.md
Outdated
|
|
||
| The Azure IoT Device Client Library provides an efficient and well tested API for connecting and using devices with the Azure IoT Hub. | ||
|
|
||
| ## client.setOptions(options, [callback]) |
There was a problem hiding this comment.
(fyi, I'm going to be asking naive questions like a customer with no knowledge of the SDK)-- in what circumstance would I add a callback to the setOptions call?
There was a problem hiding this comment.
callback is if you're using client.setOptions in the traditional node callback way, where once it completes the callback is used to move on to the next operation. In the Node Promises syntax you would not need a callback, and just call await on the setOptions: await client.setOptions(options);
There was a problem hiding this comment.
ok got it, as long as customers understand the use here--- as a javascript developer seems pretty straightforward
doc/device_client.md
Outdated
| - `modelId`: !!Digital Twin Use Only!! String used in MQTT username setting the Digital Twin modelId. | ||
| - `tokenRenewal`: Optional object with token renewal values. Only use with authentication that uses pre shared keys. | ||
| - `mqtt`: Options specific to the MQTT transport | ||
| - `webSocketAgent`: [Agent]{@link https://nodejs.org/api/https.html#https_class_https_agent} object to use with MQTT-WS connections. Can be used for tunneling proxies. |
There was a problem hiding this comment.
in the case of protocol specific options, do I need to specify the protocol? Or will a call to client.SetOptions(webSocketAgent=xxx) automatically work for whichever protocol I'm using (assuming amqp or mqtt in this case based on the parameter name)
There was a problem hiding this comment.
This is incorrect. what's a good way to guide users that they need to put it in an object?
i.e.: client.setOptions({mqtt: {websocketAgent: agent}}
(also, I know the API looks kinda dumb, since all three can accept an agent, but,,, that's just how it is and we can't break it now).
There was a problem hiding this comment.
yeah it's fine, doesn't have to be perfect as long as it's usable-- in this case, probably best to just show an example. As in, before starting the protocol specific examples with mqtt, a line saying:
Protocol specific options: to use options for a specific protocol, you must pass it as an object that specifies both the protocol used and the option you are setting. For example, client.setOptions({mqtt: {websocketAgent: agent}}).
|
|
||
| Used directly after creating the Device Client to set options on the client. These should not be dynamically altered during runtime of the device client. | ||
|
|
||
| ### Available Options |
There was a problem hiding this comment.
Will these options also show up somewhere in API reference docs?
There was a problem hiding this comment.
ok, should they? seems to me like it would be helpful but if that's breaking API reference doc precedent that's fine
There was a problem hiding this comment.
wait sorry, these options do show up in the API somewhere, but not in this form. I pulled most of the definitions for the options from the docstrings.
doc/device_client.md
Outdated
| - `drain`: Boolean indicating whether only one message should be received all messages should be drained. | ||
| - `amqp`: Options specific to the AMQP transport | ||
| - `webSocketAgent`: [Agent]{@link https://nodejs.org/api/https.html#https_class_https_agent} object to use with AMQP-WS connections. Can be used for tunneling proxies. | ||
| - `cert`: X509 Certificate. |
There was a problem hiding this comment.
Could you please expand this cert one to be
X.509 certificate used for authenticating the device to the IoTHub.
Part of this is adding clarity where the Device Client supports Proxy. It is also consolidating our documentation for setOptions into a file, a new "README" for the Device Client that is linked from the main readme. Maybe the better place should be the Wiki... Unclear. That can be discussed @elhorton.