| "description": "Ping and trace route to many hosts at once.", |
| "name": "Stephen Vickers", |
| "email": "stephen.vickers.sv@gmail.com" |
| "url": "https://bitbucket.org/stephenwvickers/node-net-ping" |
| "name": "Stephen Vickers", |
| "email": "stephen.vickers.sv@gmail.com" |
| "readme": "\n# net-ping - [homepage][homepage]\n\nThis module implements ICMP Echo (ping) support for [Node.js][nodejs].\n\nThis module is installed using [node package manager (npm)][npm]:\n\n npm install net-ping\n\nIt is loaded using the `require()` function:\n\n var ping = require (\"net-ping\");\n\nA ping session can then be created to ping or trace route to many hosts:\n\n var session = ping.createSession ();\n\n session.pingHost (target, function (error, target) {\n if (error)\n console.log (target + \": \" + error.toString ());\n else\n console.log (target + \": Alive\");\n });\n\n[homepage]: http://re-tool.org \"Homepage\"\n[nodejs]: http://nodejs.org \"Node.js\"\n[npm]: https://npmjs.org/ \"npm\"\n\n# Network Protocol Support\n\nThis module supports IPv4 using the ICMP, and IPv6 using the ICMPv6.\n\n# Error Handling\n\nEach request exposed by this module requires one or more mandatory callback\nfunctions. Callback functions are typically provided an `error` argument.\n\nAll errors are sub-classes of the `Error` class. For timed out errors the\nerror passed to the callback function will be an instance of the\n`ping.RequestTimedOutError` class, with the exposed `message` attribute set\nto `Request timed out`.\n\nThis makes it easy to determine if a host responded, a time out occurred, or\nwhether an error response was received:\n\n session.pingHost (\"1.2.3.4\", function (error, target) {\n if (error)\n if (error instanceof ping.RequestTimedOutError)\n console.log (target + \": Not alive\");\n else\n console.log (target + \": \" + error.toString ());\n else\n console.log (target + \": Alive\");\n });\n\nIn addition to the the `ping.RequestTimedOutError` class, the following errors\nare also exported by this module to wrap ICMP error responses:\n\n * `DestinationUnreachableError`\n * `PacketTooBigError`\n * `ParameterProblemError`\n * `RedirectReceivedError`\n * `SourceQuenchError`\n * `TimeExceededError`\n\nThese errors are typically reported by hosts other than the intended target.\nIn all cases each class exposes a `source` attribute which will specify the\nhost who reported the error (which could be the intended target). This will\nalso be included in the errors `message` attribute, i.e.:\n\n $ sudo node example/ping-ttl.js 1 192.168.2.10 192.168.2.20 192.168.2.30\n 192.168.2.10: Alive\n 192.168.2.20: TimeExceededError: Time exceeded (source=192.168.1.1)\n 192.168.2.30: Not alive\n\nThe `Session` class will emit an `error` event for any other error not\ndirectly associated with a request. This is typically an instance of the\n`Error` class with the errors `message` attribute specifying the reason.\n\n# Packet Size\n\nBy default ICMP echo request packets sent by this module are 16 bytes in size.\nSome implementations cannot cope with such small ICMP echo requests. For\nexample, some implementations will return an ICMP echo reply, but will include\nan incorrect ICMP checksum.\n\nThis module exposes a `packetSize` option to the `createSession()` method which\nspecifies how big ICMP echo request packets should be:\n\n var session = ping.createSession ({packetSize: 64});\n\n# Round Trip Times\n\nSome callbacks used by methods exposed by this module provide two instances of\nthe JavaScript `Date` class specifying when the first ping was sent for a\nrequest, and when a request completed.\n\nThese parameters are typically named `sent` and `rcvd`, and are provided to\nhelp round trip time calculation.\n\nA request can complete in one of two ways. In the first, a ping response is\nreceived and `rcvd - sent` will yield the round trip time for the request in\nmilliseconds.\n\nIn the second, no ping response is received resulting in a request time out.\nIn this case `rcvd - sent` will yield the total time spent waiting for each\nretry to timeout if any. For example, if the `retries` option to the\n`createSession()` method was specified as `2` and `timeout` as `2000` then\n`rcvd - sent` will yield more than `6000` milliseconds.\n\nAlthough this module provides instances of the `Date` class to help round trip\ntime calculation the dates and times represented in each instance should not be\nconsidered 100% accurate.\n\nEnvironmental conditions can affect when a date and time is actually\ncalculated, e.g. garbage collection introducing a delay or the receipt of many\npackets at once. There are also a number of functions through which received\npackets must pass, which can also introduce a slight variable delay.\n\nThroughout development experience has shown that, in general the smaller the\nround trip time the less accurate it will be - but the information is still\nuseful nonetheless.\n\n# Constants\n\nThe following sections describe constants exported and used by this module.\n\n## ping.NetworkProtocol\n\nThis object contains constants which can be used for the `networkProtocol`\noption to the `createSession()` function exposed by this module. This option\nspecifies the IP protocol version to use when creating the raw socket.\n\nThe following constants are defined in this object:\n\n * `IPv4` - IPv4 protocol\n * `IPv6` - IPv6 protocol\n\n# Using This Module\n\nThe `Session` class is used to issue ping and trace route requests to many\nhosts. This module exports the `createSession()` function which is used to\ncreate instances of the `Session` class.\n\n## ping.createSession ([options])\n\nThe `createSession()` function instantiates and returns an instance of the\n`Session` class:\n\n // Default options\n var options = {\n networkProtocol: ping.NetworkProtocol.IPv4,\n packetSize: 16,\n retries: 1,\n sessionId: (process.pid % 65535),\n timeout: 2000,\n ttl: 128\n };\n \n var session = ping.createSession (options);\n\nThe optional `options` parameter is an object, and can contain the following\nitems:\n\n * `networkProtocol` - Either the constant `ping.NetworkProtocol.IPv4` or the\n constant `ping.NetworkProtocol.IPv6`, defaults to the constant\n `ping.NetworkProtocol.IPv4`\n * `packetSize` - How many bytes each ICMP echo request packet should be,\n defaults to `16`, if the value specified is less that `12` then the value\n `12` will be used (8 bytes are required for the ICMP packet itself, then 4\n bytes are required to encode a unique session ID in the request and response\n packets)\n * `retries` - Number of times to re-send a ping requests, defaults to `1`\n * `sessionId` - A unique ID used to identify request and response packets sent\n by this instance of the `Session` class, valid numbers are in the range of\n `1` to `65535`, defaults to the value of `process.pid % 65535`\n * `timeout` - Number of milliseconds to wait for a response before re-trying\n or failing, defaults to `2000`\n * `ttl` - Value to use for the IP header time to live field, defaults to `128`\n\nAfter creating the ping `Session` object an underlying raw socket will be\ncreated. If the underlying raw socket cannot be opened an exception with be\nthrown. The error will be an instance of the `Error` class.\n\nSeperate instances of the `Session` class must be created for IPv4 and IPv6.\n\n## session.on (\"close\", callback)\n\nThe `close` event is emitted by the session when the underlying raw socket\nis closed.\n\nNo arguments are passed to the callback.\n\nThe following example prints a message to the console when the underlying raw\nsocket is closed:\n\n session.on (\"close\", function () {\n console.log (\"socket closed\");\n });\n\n## session.on (\"error\", callback)\n\nThe `error` event is emitted by the session when the underlying raw socket\nemits an error.\n\nThe following arguments will be passed to the `callback` function:\n\n * `error` - An instance of the `Error` class, the exposed `message` attribute\n will contain a detailed error message.\n\nThe following example prints a message to the console when an error occurs\nwith the underlying raw socket, the session is then closed:\n\n session.on (\"error\", function (error) {\n console.log (error.toString ());\n session.close ();\n });\n\n## session.close ()\n\nThe `close()` method closes the underlying raw socket, and cancels all\noutstanding requsts.\n\nThe calback function for each outstanding ping requests will be called. The\nerror parameter will be an instance of the `Error` class, and the `message`\nattribute set to `Socket forcibly closed`.\n\nThe sessoin can be re-used simply by submitting more ping requests, a new raw\nsocket will be created to serve the new ping requests. This is a way in which\nto clear outstanding requests.\n\nThe following example submits a ping request and prints the target which\nsuccessfully responded first, and then closes the session which will clear the\nother outstanding ping requests.\n\n var targets = [\"1.1.1.1\", \"2.2.2.2\", \"3.3.3.3\"];\n \n for (var i = 0; i < targets.length; i++) {\n session.pingHost (targets[i], function (error, target) {\n if (! error) {\n console.log (target);\n session.close (); \n }\n });\n }\n\n## session.pingHost (target, callback)\n\nThe `pingHost()` method sends a ping request to a remote host.\n\nThe `target` parameter is the dotted quad formatted IP address of the target\nhost for IPv4 sessions, or the compressed formatted IP address of the target\nhost for IPv6 sessions.\n\nThe `callback` function is called once the ping requests is complete. The\nfollowing arguments will be passed to the `callback` function:\n\n * `error` - Instance of the `Error` class or a sub-class, or `null` if no\n error occurred\n * `target` - The target parameter as specified in the request\n still be the target host and NOT the responding gateway\n * `sent` - An instance of the `Date` class specifying when the first ping\n was sent for this request (refer to the Round Trip Time section for more\n information)\n * `rcvd` - An instance of the `Date` class specifying when the request\n completed (refer to the Round Trip Time section for more information)\n\nThe following example sends a ping request to a remote host:\n\n var target = \"fe80::a00:27ff:fe2a:3427\";\n\n session.pingHost (target, function (error, target, sent, rcvd) {\n var ms = rcvd - sent;\n if (error)\n console.log (target + \": \" + error.toString ());\n else\n console.log (target + \": Alive (ms=\" + ms + \")\");\n });\n\n## session.traceRoute (target, ttl, feedCallback, doneCallback)\n\nThe `traceRoute()` method provides similar functionality to the trace route\nutility typically provided with most networked operating systems.\n\nThe `target` parameter is the dotted quad formatted IP address of the target\nhost for IPv4 sessions, or the compressed formatted IP address of the target\nhost for IPv6 sessions. The optional `ttl` parameter specifies the maximum\nnumber of hops used by the trace route and defaults to the `ttl` options\nparameter as defined by the `createSession()` method.\n\nSome hosts do not respond to ping requests when the time to live is `0`, that\nis they will not send back an time exceeded error response. Instead of\nstopping the trace route at the first time out this method will move on to the\nnext hop, by increasing the time to live by 1. It will do this 2 times,\nmeaning that a trace route will continue until the target host responds or at\nmost 3 request time outs are experienced.\n\nEach requst is subject to the `retries` and `timeout` option parameters to the\n`createSession()` method. That is, requests will be retried per hop as per\nthese parameters.\n\nThis method will not call a single callback once the trace route is complete.\nInstead the `feedCallback` function will be called each time a ping response is\nreceived or a time out occurs. The following arguments will be passed to the\n`feedCallback` function:\n\n * `error` - Instance of the `Error` class or a sub-class, or `null` if no\n error occurred\n * `target` - The target parameter as specified in the request\n * `ttl` - The time to live used in the request which triggered this respinse\n * `sent` - An instance of the `Date` class specifying when the first ping\n was sent for this request (refer to the Round Trip Time section for more\n information)\n * `rcvd` - An instance of the `Date` class specifying when the request\n completed (refer to the Round Trip Time section for more information)\n\nOnce a ping response has been received from the target, or more than three\nrequest timed out errors are experienced, the `doneCallback` function will be\ncalled. The following arguments will be passed to the `doneCallback` function:\n\n * `error` - Instance of the `Error` class or a sub-class, or `null` if no\n error occurred\n * `target` - The target parameter as specified in the request\n\nOnce the `doneCallback` function has been called the request is complete and\nthe `requestCallback` function will no longer be called.\n\nIf the `feedCallback` function returns a true value when called the trace route\nwill stop and the `doneCallback` will be called.\n\nThe following example initiates a trace route to a remote host:\n\n function doneCb (error, target) {\n if (error)\n console.log (target + \": \" + error.toString ());\n else\n console.log (target + \": Done\");\n }\n\n function feedCb (error, target, ttl, sent, rcvd) {\n var ms = rcvd - sent;\n if (error) {\n if (error instanceof ping.TimeExceededError) {\n console.log (target + \": \" + error.source + \" (ttl=\"\n + ttl + \" ms=\" + ms +\")\");\n } else {\n console.log (target + \": \" + error.toString ()\n + \" (ttl=\" + ttl + \" ms=\" + ms +\")\");\n }\n } else {\n console.log (target + \": \" + target + \" (ttl=\" + ttl\n + \" ms=\" + ms +\")\");\n }\n }\n\n session.traceRoute (\"192.168.10.10\", 10, feedCb, doneCb);\n\n# Example Programs\n\nExample programs are included under the modules `example` directory.\n\n# Bugs & Known Issues\n\nNone, yet!\n\nBug reports should be sent to <stephen.vickers.sv@gmail.com>.\n\n# Changes\n\n## Version 1.0.0 - 03/02/2013\n\n * Initial release\n\n## Version 1.0.1 - 04/02/2013\n\n * Minor corrections to the README.md\n * Add note to README.md about error handling\n * Timed out errors are now instances of the `ping.RequestTimedOutError`\n object\n\n## Version 1.0.2 - 11/02/2013\n\n * The RequestTimedOutError class is not being exported\n\n## Version 1.1.0 - 13/02/2013\n\n * Support IPv6\n\n## Version 1.1.1 - 15/02/2013\n\n * The `ping.Session.close()` method was not undefining the sessions raw\n socket after closing\n * Return self from the `pingHost()` method to chain method calls \n\n## Version 1.1.2 - 04/03/2013\n\n * Use the `raw.Socket.pauseRecv()` and `raw.Socket.resumeRecv()` methods\n instead of closing a socket when there are no more outstanding requests\n\n## Version 1.1.3 - 07/03/2013\n\n * Sessions were limited to sending 65535 ping requests\n\n## Version 1.1.4 - 09/04/2013\n\n * Add the `packetSize` option to the `createSession()` method to specify how\n many bytes each ICMP echo request packet should be\n\n## Version 1.1.5 - 17/05/2013\n\n * Incorrectly parsing ICMP error responses resulting in responses matching\n the wrong request\n * Use a unique session ID per instance of the `Session` class to identify\n requests and responses sent by a session\n * Added the (internal) `_debugRequest()` and `_debugResponse()` methods, and\n the `_debug` option to the `createSession()` method\n * Added example programs `ping-ttl.js` and `ping6-ttl.js`\n * Use MIT license instead of GPL\n\n## Version 1.1.6 - 17/05/2013\n\n * Session IDs are now 2 bytes (previously 1 byte), and request IDs are also\n now 2 bytes (previously 3 bytes)\n * Each ICMP error response now has an associated error class (e.g. the\n `Time exceeded` response maps onto the `ping.TimeExceededError` class)\n * Call request callbacks with an error when there are no free request IDs\n because of too many outstanding requests\n\n## Version 1.1.7 - 19/05/2013\n\n * Added the `traceRoute()` method\n * Added the `ttl` option parameter to the `createSession()` method, and\n updated the example programs `ping-ttl.js` and `ping6-ttl.js` to use it\n * Response callback for `pingHost()` now includes two instances of the\n `Date` class to specify when a request was sent and a response received\n\n## Version 1.1.8 - 01/07/2013\n\n * Use `raw.Socket.createChecksum()` instead of automatic checksum generation\n\n## Version 1.1.9 - 01/07/2013\n\n * Use `raw.Socket.writeChecksum()` instead of manually rendering checksums\n\n# Roadmap\n\nSuggestions and requirements should be sent to <stephen.vickers.sv@gmail.com>.\n\n# License\n\nCopyright (c) 2013 Stephen Vickers\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n\n# Author\n\nStephen Vickers <stephen.vickers.sv@gmail.com>\n", |
| "readmeFilename": "README.md", |
| "shasum": "7e70d3a2a766b060d281b17686e94ff4948e26c0" |
| "_resolved": "https://registry.npmjs.org/net-ping/-/net-ping-1.1.9.tgz" |
