Also discussed on the ml.
Changelog for the c-ares project
+* Dec 3 2008 (Daniel Stenberg)
+
+ API changes:
+
+ I made sure the public ares_config struct looks like before and yet it
+ supports the ROTATE option thanks to c-ares now storing the "optmask"
+ internally. Thus we should be ABI compatible with the past release(s)
+ now. My efforts mentioned below should not break backwards ABI compliance.
+
+ Here's how I suggest we proceed with the API:
+
+ ares_init() will be primary "channel creator" function.
+
+ ares_init_options() will continue to work exactly like now and before. For
+ starters, it will be the (only) way to set the existing options.
+
+ ares_save_options() will continue to work like today, but will ONLY save
+ options that you can set today (including ARES_OPT_ROTATE actually) but new
+ options that we add may not be saved with this.
+
+ Instead we introduce:
+
+ ares_dup() that instead can make a new channel and clone the config used
+ from an existing channel. It will then clone all config options, including
+ future new things we add.
+
+ ares_set_*() style functions that set (new) config options. As a start we
+ simply add these for new functionality, but over time we can also introduce
+ them for existing "struct ares_options" so that we can eventually deprecate
+ the two ares_*_options() functions.
+
+ ares_get_*() style functions for extracting info from a channel handle that
+ should be used instead of ares_save_options().
+
* Nov 26 2008 (Yang Tse)
- Brad Spencer provided changes to allow buildconf to work on OS X.
ares_parse_a_reply.3 ares_parse_ptr_reply.3 ares_process.3 \
ares_query.3 ares_search.3 ares_send.3 ares_strerror.3 ares_timeout.3 \
ares_version.3 ares_cancel.3 ares_parse_aaaa_reply.3 ares_getnameinfo.3 \
- ares_getsock.3 ares_parse_ns_reply.3 \
+ ares_getsock.3 ares_parse_ns_reply.3 ares_dup.3 \
ares_destroy_options.3 ares_save_options.3 ares_gethostbyname_file.3
/* $Id$ */
/* Copyright 1998 by the Massachusetts Institute of Technology.
- * Copyright (C) 2007 by Daniel Stenberg
+ * Copyright (C) 2007-2008 by Daniel Stenberg
*
* Permission to use, copy, modify, and distribute this
* software and its documentation for any purpose and without
struct apattern;
+/* NOTE about the ares_options struct to users and developers.
+
+ This struct will remain looking like this. It will not be extended nor
+ shrunk in future releases, but all new options will be set by ares_set_*()
+ options instead of with the ares_init_options() function.
+
+ Eventually (in a galaxy far far away), all options will be settable by
+ ares_set_*() options and the ares_init_options() function will become
+ deprecated.
+
+ ares_save_options() is considered deprecated as of right now. Use ares_dup()
+ instead!
+
+ So, if new options are added they are not added to this struct. And they
+ are not "saved" with the ares_save_options() function but instead we
+ encourage the use of the ares_dup() function. Needless to say, if you add
+ config options to c-ares you need to make sure ares_dup() duplicates this
+ new option.
+
+ */
struct ares_options {
int flags;
int timeout; /* in seconds or milliseconds, depending on options */
int ares_init(ares_channel *channelptr);
int ares_init_options(ares_channel *channelptr, struct ares_options *options,
int optmask);
-int ares_save_options(ares_channel channel, struct ares_options *options, int *optmask);
+int ares_save_options(ares_channel channel, struct ares_options *options,
+ int *optmask);
void ares_destroy_options(struct ares_options *options);
+int ares_dup(ares_channel *dest, ares_channel src);
void ares_destroy(ares_channel channel);
void ares_cancel(ares_channel channel);
void ares_send(ares_channel channel, const unsigned char *qbuf, int qlen,
--- /dev/null
+.\" $Id$
+.\"
+.\" Copyright (C) 2007-2008 by Daniel Stenberg
+.\"
+.\" Permission to use, copy, modify, and distribute this
+.\" software and its documentation for any purpose and without
+.\" fee is hereby granted, provided that the above copyright
+.\" notice appear in all copies and that both that copyright
+.\" notice and this permission notice appear in supporting
+.\" documentation, and that the name of M.I.T. not be used in
+.\" advertising or publicity pertaining to distribution of the
+.\" software without specific, written prior permission.
+.\" M.I.T. makes no representations about the suitability of
+.\" this software for any purpose. It is provided "as is"
+.\" without express or implied warranty.
+.\"
+.TH ARES_DUP 3 "2 Dec 2008"
+.SH NAME
+ares_dup \- Duplicate a resolver channel
+.SH SYNOPSIS
+.nf
+.B #include <ares.h>
+.PP
+.B int ares_dup(ares_channel *\fIchannel\fP, ares_channel \fIsource\fP)
+.fi
+.SH DESCRIPTION
+The \fBares_dup(3)\fP function duplicates an existing communications channel
+for name service lookups. If it returns successfully, \fBares_dup(3)\fP will
+set the variable pointed to by \fIchannel\fP to a handle used to identify the
+name service channel. The caller should invoke \fIares_destroy(3)\fP on the
+handle when the channel is no longer needed.
+
+The \fBares_dup_options\fP function also initializes a name service channel,
+with additional options set exactly as the \fIsource\fP channel has them
+configured.
+.SH SEE ALSO
+.BR ares_destroy(3),
+.BR ares_init(3)
+.SH AVAILABILITY
+ares_dup(3) was added in c-ares 1.6.0
+.SH AUTHOR
+Daniel Stenberg
+
.B ARES_ENOMEM
The process's available memory was exhausted.
.SH SEE ALSO
-.BR ares_destroy (3)
+.BR ares_destroy(3),
+.BR ares_dup(3)
.SH AUTHOR
Greg Hudson, MIT Information Systems
.br
return ARES_SUCCESS;
}
+/* ares_dup() duplicates a channel handle with all its options and returns a
+ new channel handle */
+int ares_dup(ares_channel *dest, ares_channel src)
+{
+ struct ares_options opts;
+ int rc;
+ int optmask;
+
+ *dest = NULL; /* in case of failure return NULL explicitly */
+
+ /* First get the options supported by the old ares_save_options() function,
+ which is most of them */
+ rc = ares_save_options(src, &opts, &optmask);
+ if(rc)
+ return rc;
+
+ /* Then create the new channel with those options */
+ rc = ares_init_options(dest, &opts, optmask);
+
+ /* destroy the options copy to not leak any memory */
+ ares_destroy_options(&opts);
+
+ if(rc)
+ return rc;
+
+ /* Now clone the options that ares_save_options() doesn't support. */
+
+ /* No such options available yet */
+
+ return ARES_SUCCESS; /* everything went fine */
+
+}
+
/* Save options from initialized channel */
int ares_save_options(ares_channel channel, struct ares_options *options,
int *optmask)
.B void ares_save_options(ares_channel \fIchannel\fP, struct ares_options *\fIoptions\fP, int *\fIoptmask\fP)
.fi
.SH DESCRIPTION
-The
-.B ares_save_options
-function saves the channel data identified by
+The \fBares_save_options(3)\fP function saves the channel data identified by
.IR channel ,
into the options struct identified by
.IR options ,
passed directly to ares_init_options. When the options
are no longer needed, ares_destroy_options should be called
to free any associated memory.
-
-
+.SH NOTE
+Since c-ares 1.6.0 the ares_options struct has been "locked" meaning that it
+won't be extended to cover new funtions. This function will remain
+functioning, but it can only return config data that can be represented in
+this config struct, which may no longer be the complete set of config
+options. \fBares_dup(3)\fP will not have that restriction.
.SH SEE ALSO
.BR ares_destroy_options (3),
-.BR ares_init_options (3)
+.BR ares_init_options (3),
+.BR ares_dup (3)
+.SH AVAILABILITY
+ares_save_options(3) was added in c-ares 1.4.0
.SH AUTHOR
Brad House
.br
projects / curl / commitdiff