Pinger.h 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107
  1. /* vim: set expandtab ts=4 sw=4: */
  2. /*
  3. * You may redistribute this program and/or modify it under the terms of
  4. * the GNU General Public License as published by the Free Software Foundation,
  5. * either version 3 of the License, or (at your option) any later version.
  6. *
  7. * This program is distributed in the hope that it will be useful,
  8. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  9. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  10. * GNU General Public License for more details.
  11. *
  12. * You should have received a copy of the GNU General Public License
  13. * along with this program. If not, see <https://www.gnu.org/licenses/>.
  14. */
  15. #ifndef Pinger_H
  16. #define Pinger_H
  17. #include "benc/String.h"
  18. #include "memory/Allocator.h"
  19. #include "util/log/Log.h"
  20. #include "crypto/random/Random.h"
  21. #include "util/events/EventBase.h"
  22. #include "util/Linker.h"
  23. Linker_require("util/Pinger.c")
  24. /**
  25. * On pong received callback.
  26. * This is called when a response to the ping comes in.
  27. *
  28. * @param data the response content or NULL if the ping timed out, if Pinger_ping() was called with
  29. * null, this will be an empty string.
  30. * @param milliseconds the number of milliseconds between the sending of the ping and this event.
  31. * @param context the context which is set in the Pinger_Ping struct returned by Pinger_ping().
  32. */
  33. #define Pinger_ON_RESPONSE(x) \
  34. void (* x)(String* data, uint32_t milliseconds, void* context)
  35. /**
  36. * Sender callback.
  37. * The pinger uses this user provided function to send the ping.
  38. * This function does not return, in the event of error, it is the user's responsibility to
  39. * communicate the error through the context back to the function which called Pinger_ping().
  40. *
  41. * @param data the content of the ping to send.
  42. * @param context the context which is set in the Pinger_Ping struct returned by Pinger_ping().
  43. */
  44. #define Pinger_SEND_PING(x) void (* x)(String* data, void* context)
  45. struct Pinger;
  46. struct Pinger_Ping
  47. {
  48. /**
  49. * The allocator which is set by Pinger_ping() and can be used to
  50. * allocate space which will be freed when the ping completes.
  51. */
  52. struct Allocator* pingAlloc;
  53. /** How the ping will be identified on the wire. */
  54. uint32_t handle;
  55. /**
  56. * This is NULL by default and is set by the caller of Pinger_ping(),
  57. * when sendPing() and onResponse() are called, whatever this is, will be passed to them.
  58. */
  59. void* context;
  60. };
  61. /**
  62. * @param data this is the bytes that you want to be reflected back to you.
  63. * @param onResponse this function will be called when the ping is responded to or times out.
  64. * @param sendPing the function which will be called to send the ping out to the other node.
  65. * @param timeoutMilliseconds the number of milliseconds to wait before timeout.
  66. * @param allocator cancel the ping by freeing this allocator.
  67. * @param pinger
  68. * @return a new Pinger_Ping if all goes well, NULL if there is no space.
  69. */
  70. struct Pinger_Ping* Pinger_newPing(String* data,
  71. Pinger_ON_RESPONSE(onResponse),
  72. Pinger_SEND_PING(sendPing),
  73. uint32_t timeoutMilliseconds,
  74. struct Allocator* allocator,
  75. struct Pinger* pinger);
  76. /**
  77. * Function to call when data comes in which appears to be a ping response.
  78. *
  79. * @param data the data as it comes in.
  80. * @param pinger the pinger context.
  81. */
  82. void Pinger_pongReceived(String* data, struct Pinger* pinger);
  83. /**
  84. * Create a new pinger.
  85. *
  86. * @param eventBase
  87. * @param logger
  88. * @param alloc
  89. */
  90. struct Pinger* Pinger_new(struct EventBase* eventBase,
  91. struct Random* rand,
  92. struct Log* logger,
  93. struct Allocator* alloc);
  94. #endif