pythonmod/doc/modules/functions.rst

   1 Scriptable functions
   2 ====================
   3
   4 Network
   5 -------
   6
   7 .. function:: ntohs(netshort)
   8
   9    This subroutine converts values between the host and network byte order.
  10    Specifically, **ntohs()** converts 16-bit quantities from network byte order
  11    to host byte order.
  12
  13    :param netshort: 16-bit short addr
  14    :rtype: converted addr
  15
  16
  17 Cache
  18 -----
  19
  20 .. function:: storeQueryInCache(qstate, qinfo, msgrep, is_referral)
  21
  22    Store pending query in local cache.
  23
  24    :param qstate: :class:`module_qstate`
  25    :param qinfo: :class:`query_info`
  26    :param msgrep: :class:`reply_info`
  27    :param is_referral: integer
  28    :rtype: boolean
  29
  30 .. function:: invalidateQueryInCache(qstate, qinfo)
  31
  32    Invalidate record in local cache.
  33
  34    :param qstate: :class:`module_qstate`
  35    :param qinfo: :class:`query_info`
  36
  37
  38 EDNS options
  39 ------------
  40
  41 .. function:: register_edns_option(env, code, bypass_cache_stage=False, no_aggregation=False)
  42
  43     Register EDNS option code.
  44
  45     :param env: :class:`module_env`
  46     :param code: option code(integer)
  47     :param bypass_cache_stage: whether to bypass the cache response stage
  48     :param no_aggregation: whether this query should be unique
  49     :return: ``1`` if successful, ``0`` otherwise
  50     :rtype: integer
  51
  52 .. function:: edns_opt_list_find(list, code)
  53
  54     Find the EDNS option code in the EDNS option list.
  55
  56     :param list: linked list of :class:`edns_option`
  57     :param code: option code (integer)
  58     :return: the edns option if found or None
  59     :rtype: :class:`edns_option` or None
  60
  61 .. function:: edns_opt_list_remove(list, code);
  62
  63     Remove an ENDS option code from the list.
  64     .. note:: All :class:`edns_option` with the code will be removed
  65
  66     :param list: linked list of :class:`edns_option`
  67     :param code: option code (integer)
  68     :return: ``1`` if at least one :class:`edns_option` was removed, ``0`` otherwise
  69     :rtype: integer
  70
  71 .. function:: edns_opt_list_append(list, code, data, region)
  72
  73     Append given EDNS option code with data to the list.
  74
  75     :param list: linked list of :class:`edns_option`
  76     :param code: option code (integer)
  77     :param data: EDNS data. **Must** be a :class:`bytearray`
  78     :param region: :class:`regional`
  79
  80 .. function:: edns_opt_list_is_empty(list)
  81
  82     Check if an EDNS option list is empty.
  83
  84     :param list: linked list of :class:`edns_option`
  85     :return: ``1`` if list is empty, ``0`` otherwise
  86     :rtype: integer
  87
  88
  89 Inplace callbacks
  90 -----------------
  91
  92 .. function:: inplace_cb_reply(qinfo, qstate, rep, rcode, edns, opt_list_out, region, \*\*kwargs)
  93
  94     Function prototype for callback functions used in
  95     `register_inplace_cb_reply`_, `register_inplace_cb_reply_cache`_,
  96     `register_inplace_cb_reply_local` and `register_inplace_cb_reply_servfail`.
  97
  98     :param qinfo: :class:`query_info`
  99     :param qstate: :class:`module_qstate`
 100     :param rep: :class:`reply_info`
 101     :param rcode: return code (integer), check ``RCODE_`` constants.
 102     :param edns: :class:`edns_data`
 103     :param opt_list_out: :class:`edns_option`. EDNS option list to append options to.
 104     :param region: :class:`regional`
 105     :param \*\*kwargs: Dictionary that may contain parameters added in a future
 106         release. Current parameters:
 107         ``repinfo``: :class:`comm_reply`. Reply information for a communication point.
 108
 109 .. function:: inplace_cb_query(qinfo, flags, qstate, addr, zone, region)
 110
 111     Function prototype for callback functions used in
 112     `register_inplace_cb_query`_.
 113
 114     :param qinfo: :class:`query_info`
 115     :param flags: query flags (integer)
 116     :param qstate: :class:`module_qstate`
 117     :param addr: :class:`sockaddr_storage`
 118     :param zone: zone name in wire format (bytes)
 119     :param region: :class:`regional`
 120
 121 .. function:: register_inplace_cb_reply(py_cb, env, id)
 122
 123     Register py_cb as an inplace reply callback function.
 124
 125     :param py_cb: Python function that follows `inplace_cb_reply`_'s prototype. **Must** be callable.
 126     :param env: :class:`module_env`
 127     :param id: Module ID.
 128     :return: True on success, False otherwise
 129     :rtype: boolean
 130
 131 .. function:: register_inplace_cb_reply_cache(py_cb, env, id)
 132
 133     Register py_cb as an inplace reply_cache callback function.
 134
 135     :param py_cb: Python function that follows `inplace_cb_reply`_'s prototype. **Must** be callable.
 136     :param env: :class:`module_env`
 137     :param id: Module ID.
 138     :return: True on success, False otherwise
 139     :rtype: boolean
 140
 141 .. function:: register_inplace_cb_reply_local(py_cb, env, id)
 142
 143     Register py_cb as an inplace reply_local callback function.
 144
 145     :param py_cb: Python function that follows `inplace_cb_reply`_'s prototype. **Must** be callable.
 146     :param env: :class:`module_env`
 147     :param id: Module ID.
 148     :return: True on success, False otherwise
 149     :rtype: boolean
 150
 151 .. function:: register_inplace_cb_reply_servfail(py_cb, env, id)
 152
 153     Register py_cb as an inplace reply_servfail callback function.
 154
 155     :param py_cb: Python function that follows `inplace_cb_reply`_'s prototype. **Must** be callable.
 156     :param env: :class:`module_env`
 157     :param id: Module ID.
 158     :return: True on success, False otherwise
 159     :rtype: boolean
 160
 161 .. function:: register_inplace_cb_query(py_cb, env, id)
 162
 163     Register py_cb as an inplace query callback function.
 164
 165     :param py_cb: Python function that follows `inplace_cb_query`_'s prototype. **Must** be callable.
 166     :param env: :class:`module_env`
 167     :param id: Module ID.
 168     :return: True on success, False otherwise
 169     :rtype: boolean
 170
 171 Logging
 172 -------
 173
 174 .. function:: verbose(level, msg)
 175
 176    Log a verbose message, pass the level for this message.
 177    No trailing newline is needed.
 178
 179    :param level: verbosity level for this message, compared to global verbosity setting.
 180    :param msg: string message
 181
 182 .. function:: log_info(msg)
 183
 184    Log informational message. No trailing newline is needed.
 185
 186    :param msg: string message
 187
 188 .. function:: log_err(msg)
 189
 190    Log error message. No trailing newline is needed.
 191
 192    :param msg: string message
 193
 194 .. function:: log_warn(msg)
 195
 196    Log warning message. No trailing newline is needed.
 197
 198    :param msg: string message
 199
 200 .. function:: log_hex(msg, data, length)
 201
 202    Log a hex-string to the log. Can be any length.
 203    performs mallocs to do so, slow. But debug useful.
 204
 205    :param msg: string desc to accompany the hexdump.
 206    :param data: data to dump in hex format.
 207    :param length: length of data.
 208
 209 .. function:: log_dns_msg(str, qinfo, reply)
 210
 211    Log DNS message.
 212
 213    :param str: string message
 214    :param qinfo: :class:`query_info`
 215    :param reply: :class:`reply_info`
 216
 217 .. function:: log_query_info(verbosity_value, str, qinf)
 218
 219    Log query information.
 220
 221    :param verbosity_value: see constants
 222    :param str: string message
 223    :param qinf: :class:`query_info`
 224
 225 .. function:: regional_log_stats(r)
 226
 227    Log regional statistics.
 228
 229    :param r: :class:`regional`
 230
 231
 232 Debugging
 233 ---------
 234
 235 .. function:: strextstate(module_ext_state)
 236
 237    Debug utility, module external qstate to string.
 238
 239    :param module_ext_state: the state value.
 240    :rtype: descriptive string.
 241
 242 .. function:: strmodulevent(module_event)
 243
 244    Debug utility, module event to string.
 245
 246    :param module_event: the module event value.
 247    :rtype: descriptive string.
 248
 249 .. function:: ldns_rr_type2str(atype)
 250
 251    Convert RR type to string.
 252
 253 .. function:: ldns_rr_class2str(aclass)
 254
 255    Convert RR class to string.