[1869] in Kerberos_V5_Development
Re: krb5-libs/66: add API versioning before next release
daemon@ATHENA.MIT.EDU (Barry Jaspan)
Tue Oct 22 18:02:49 1996
Date: Tue, 22 Oct 1996 18:01:24 -0400
From: "Barry Jaspan" <bjaspan@MIT.EDU>
To: krbdev@MIT.EDU
Cc: krb5-bugs@MIT.EDU
I propose the following changes to the krb5 api, to be made before the
next release.
* New symbols
#define KRB5_API_VERSION_MASK 0x12345100
#define KRB5_API_VERSION_1 (KRB5_API_VERSION_MASK | 0x01)
* New error codes
KRB5_BAD_API_VERSION: The value specified for api_version is not a
KRB5_API_VERSION_n constant.
KRB5_OLD_API_VERSION: The value specified for api_version is legal but
is no longer supported by this implementation.
KRB5_NEW_API_VERSION: The value specfiied for api_version is legal but
is not yet supported by this implementation.
* Header file changes
The symbol USE_KRB5_API_VERSION is defined to contain the API version
number used by the current source code being compiled. If the symbol
is not defined, the header files automatically define it to be the
newest API version supported by the library. Each krb5 header file
containing information that changes based on API version decides which
version to use based on the value of this symbol.
The krb5 libraries are entitled to assume that callers invoking them
at a given API version were compiled with the appropriate value of
USE_KRB5_API_VERSION.
* Function changes
** krb5_error_code krb5_init_api(int api_version, krb5_context *context)
Initializes the context \funcparam{*context} and the API for the
application, using the API version specified in api_version. Currently
the context contains the API version, encryption types, a pointer to
operating specific data and the default realm. In the future, the
context may be also contain thread specific data. The data in the
context should be freed with \funcname{krb5_free_context}.
Returns system errors, and KRB5_BAD_API_VERSION, KRB5_OLD_API_VERSION,
and KRB5_NEW_API_VERSION.
** krb5_error_code krb5_init_context(krb5_context *context)
This function is obsolete. For backwards compatibility, it is the
same as a call to krb5_init_api(KRB5_API_VERSION_1, context).
** krb5_init_ets(krb5_context context)
This function is now called automatically by krb5_init_api.
Applications may still call it directly but do not need to do so.
This function has been integrated into krb5_init_api to solve a
chicken and egg problem: krb5_init_api can return error codes, but
com_err cannot be used on those error codes until krb5_init_ets is
invoked, and since krb5_init_ets requires a context argument it is
impossible to call it before callng krb5_init_api.
