net.java.sip.communicator.util.dns
Class UnboundApi

java.lang.Object
  net.java.sip.communicator.util.dns.UnboundApi

public class UnboundApi
extends Object

Wrapper for the JUnbound JNI wrapper.

The JavaDoc of these methods is directly copied from libunbound, licensed as follows:

Copyright (c) 2007, NLnet Labs. All rights reserved. This software is open source. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the NLNET LABS nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Author:

Ingo Bauersachs

Nested Class Summary

static interface

UnboundApi.UnboundCallback Interface for the async resolve callback.

Constructor Summary

UnboundApi()

Method Summary

static void	addTrustAnchor(long context, String anchor) Add a trust anchor to the given context.
static void	cancelAsync(long context, int asyncId) Cancel an async query in progress.
static long	createContext() Create a resolving and validation context.
static void	deleteContext(long context) Destroy a validation context and free all its resources.
static String	errorCodeToString(int code) Convert error value to a human readable string.
static boolean	isAvailable() Indicates whether the Unbound library is loaded.
static void	processAsync(long context) Wait for a context to finish with results.
static UnboundResult	resolve(long context, String name, int rrtype, int rrclass) Perform resolution and validation of the target name.
static int	resolveAsync(long context, String name, int rrtype, int rrclass, Object data, UnboundApi.UnboundCallback cb) Perform resolution and validation of the target name.
static void	setDebugLevel(long context, int level) Set debug verbosity for the context.
static void	setForwarder(long context, String server) Set machine to forward DNS queries to, the caching resolver to use.
static void	tryLoadUnbound() Attempts to load the Unbound native library.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UnboundApi

public UnboundApi()

Method Detail

tryLoadUnbound

public static void tryLoadUnbound()

Attempts to load the Unbound native library. When successful, isAvailable() returns true.

isAvailable

public static boolean isAvailable()

Indicates whether the Unbound library is loaded.

Returns:

True when the JNI wrapper could be loaded, false otherwise.

setDebugLevel

public static void setDebugLevel(long context,
                                 int level)

Set debug verbosity for the context. Output is directed to stderr. Higher debug level gives more output.

Parameters:

context - context.

level - The debug level.

createContext

public static long createContext()

Create a resolving and validation context.

Returns:

a new context. default initialization. returns NULL on error.

deleteContext

public static void deleteContext(long context)

Destroy a validation context and free all its resources. Outstanding async queries are killed and callbacks are not called for them.

Parameters:

context - context to delete

setForwarder

public static void setForwarder(long context,
                                String server)

Set machine to forward DNS queries to, the caching resolver to use.

IP4 or IP6 address. Forwards all DNS requests to that machine, which is expected to run a recursive resolver. If the proxy is not DNSSEC-capable, validation may fail. Can be called several times, in that case the addresses are used as backup servers.

Parameters:

context - context. At this time it is only possible to set configuration before the first resolve is done.

server - address, IP4 or IP6 in string format. If the server is NULL, forwarding is disabled.

addTrustAnchor

public static void addTrustAnchor(long context,
                                  String anchor)

Add a trust anchor to the given context.

The trust anchor is a string, on one line, that holds a valid DNSKEY or DS RR.

Parameters:

context - context. At this time it is only possible to add trusted keys before the first resolve is done.

anchor - string, with zone-format RR on one line. [domainname] [TTL optional] [type] [class optional] [rdata contents]

resolve

public static UnboundResult resolve(long context,
                                    String name,
                                    int rrtype,
                                    int rrclass)
                             throws UnboundException

Perform resolution and validation of the target name.

Parameters:

context - context. The context is finalized, and can no longer accept config changes.

name - domain name in text format (a zero terminated text string).

rrtype - type of RR in host order, 1 is A (address).

rrclass - class of RR in host order, 1 is IN (for internet).

Returns:

the result data is returned in a newly allocated result structure. May be NULL on return, return value is set to an error in that case (out of memory).

Throws:

UnboundException - when an error occurred.

resolveAsync

public static int resolveAsync(long context,
                               String name,
                               int rrtype,
                               int rrclass,
                               Object data,
                               UnboundApi.UnboundCallback cb)
                        throws UnboundException

Perform resolution and validation of the target name.

Asynchronous, after a while, the callback will be called with your data and the result.

Parameters:

context - context. If no thread or process has been created yet to perform the work in the background, it is created now. The context is finalized, and can no longer accept config changes.

name - domain name in text format (a string).

rrtype - type of RR in host order, 1 is A.

rrclass - class of RR in host order, 1 is IN (for internet).

data - this data is your own data (you can pass null), and is passed on to the callback function.

cb - this is called on completion of the resolution.

Returns:

an identifier number is returned for the query as it is in progress. It can be used to cancel the query.

Throws:

UnboundException - when an error occurred.

cancelAsync

public static void cancelAsync(long context,
                               int asyncId)
                        throws UnboundException

Cancel an async query in progress. Its callback will not be called.

Parameters:

context - context.

asyncId - which query to cancel.

Throws:

UnboundException - This routine can error if the async_id passed does not exist or has already been delivered. If another thread is processing results at the same time, the result may be delivered at the same time and the cancel fails with an error. Also the cancel can fail due to a system error, no memory or socket failures.

errorCodeToString

public static String errorCodeToString(int code)

Convert error value to a human readable string.

Parameters:

code - error code from one of the Unbound functions.

Returns:

text string of the error code.

processAsync

public static void processAsync(long context)
                         throws UnboundException

Wait for a context to finish with results. Call this routine to continue processing results from the validating resolver. After the wait, there are no more outstanding asynchronous queries.

Parameters:

context - context.

Throws:

UnboundException - when an error occurred.