Permalink
Browse files

[doc] waffled a bit about error handling

  • Loading branch information...
1 parent cddb0df commit 54dbf322ee148c39e2a6ca7c31524827d5c33fed @agnat committed Dec 29, 2012
Showing with 30 additions and 1 deletion.
  1. +30 −1 doc/pages/user_guide.ejs
View
@@ -81,6 +81,8 @@ In fact you might receive more than one event per service instance. That is beca
The @name@ property is not necessarily the host name. It is a user defined string specifically meant to be displayed in the user interface. It only defaults to the host name.
+Note that the examples above intentionally omit error handling. See "Error Handling":#error_handling below on how to deal with synchronous and asynchronous errors.
+
h3(#service_types). On service types
Service type identifiers are strings used to match service instances to service queries. A service type always contains the service name and the protocol. Additionally it may contain one or more subtype identifiers. Here are some examples:
@@ -211,7 +213,34 @@ On current versions of Mac OS X a @Browser@ listening on the loopback interface
h3(#error_handling). Error Handling
-TBD.
+In production code error handling is probably a good idea. Synchronous errors are reported by throwing exceptions. EventEmitters report asynchronous errors by emitting an @error@ event. Asynchronous functions report errors by invoking their callback with an error object as first argument.
+
+Here is an example of an advertisement that is automatically restarted when an unknown error occurs. This happens for example when the systems mdns daemon is currently down. All other errors, like bad parameters, &c. are treated as fatal.
+
+bc.. var ad;
+
+function createAdvertisement() {
+ try {
+ ad = mdns.createAdvertisement(mdns.tcp('http'), 1337);
+ ad.on('error', handleError);
+ ad.start();
+ } catch (ex) {
+ handleError(ex);
+ }
+}
+
+function handleError(error) {
+ switch (error.errorCode) {
+ case mdns.kDNSServiceErr_Unknown:
+ console.warn(error);
+ setTimeout(createAdvertisement, 5000);
+ break;
+ default:
+ throw error;
+ }
+}
+
+p. All errors generated by the underlying dns_sd library have an @errorCode@ property. Fell free to extend the code above to treat other errors as non-fatal. See the API documentation under "Further Reading":#further_reading for a list of error codes. Errors generated by mdns itself do not have error codes.
h2(#reference). Reference

0 comments on commit 54dbf32

Please sign in to comment.