Mercurial > emacs
view doc/misc/sasl.texi @ 107984:bef5d1738c0b
Make variable forwarding explicit rather the using special values.
Basically, this makes the structure of buffer-local values and object
forwarding explicit in the type of Lisp_Symbols rather than use
special Lisp_Objects for that. This tends to lead to slightly more
verbose code, but is more C-like, simpler, and makes it easier to make
sure we handled all cases, among other things by letting the compiler
help us check it.
* lisp.h (enum Lisp_Misc_Type, union Lisp_Misc):
Removing forwarding objects.
(enum Lisp_Fwd_Type, enum symbol_redirect, union Lisp_Fwd): New types.
(struct Lisp_Symbol): Make the various forms of variable-forwarding
explicit rather than hiding them inside Lisp_Object "values".
(XFWDTYPE): New macro.
(XINTFWD, XBOOLFWD, XOBJFWD, XKBOARD_OBJFWD): Redefine.
(XBUFFER_LOCAL_VALUE): Remove.
(SYMBOL_VAL, SYMBOL_ALIAS, SYMBOL_BLV, SYMBOL_FWD, SET_SYMBOL_VAL)
(SET_SYMBOL_ALIAS, SET_SYMBOL_BLV, SET_SYMBOL_FWD): New macros.
(SYMBOL_VALUE, SET_SYMBOL_VALUE): Remove.
(struct Lisp_Intfwd, struct Lisp_Boolfwd, struct Lisp_Objfwd)
(struct Lisp_Buffer_Objfwd, struct Lisp_Kboard_Objfwd):
Remove the Lisp_Misc_* header.
(struct Lisp_Buffer_Local_Value): Redefine.
(BLV_FOUND, SET_BLV_FOUND, BLV_VALUE, SET_BLV_VALUE): New macros.
(struct Lisp_Misc_Any): Add filler to get the right size.
(struct Lisp_Free): Use struct Lisp_Misc_Any rather than struct
Lisp_Intfwd.
(DEFVAR_LISP, DEFVAR_LISP_NOPRO, DEFVAR_BOOL, DEFVAR_INT)
(DEFVAR_KBOARD): Allocate a forwarding object.
* data.c (do_blv_forwarding, store_blv_forwarding): New macros.
(let_shadows_global_binding_p): New function.
(union Lisp_Val_Fwd): New type.
(make_blv): New function.
(swap_in_symval_forwarding, indirect_variable, do_symval_forwarding)
(store_symval_forwarding, swap_in_global_binding, Fboundp)
(swap_in_symval_forwarding, find_symbol_value, Fset)
(let_shadows_buffer_binding_p, set_internal, default_value)
(Fset_default, Fmake_variable_buffer_local, Fmake_local_variable)
(Fkill_local_variable, Fmake_variable_frame_local)
(Flocal_variable_p, Flocal_variable_if_set_p)
(Fvariable_binding_locus):
* xdisp.c (select_frame_for_redisplay):
* lread.c (Fintern, Funintern, init_obarray, defvar_int)
(defvar_bool, defvar_lisp_nopro, defvar_lisp, defvar_kboard):
* frame.c (store_frame_param):
* eval.c (Fdefvaralias, Fuser_variable_p, specbind, unbind_to):
* bytecode.c (Fbyte_code) <varref, varset>: Adapt to the new symbol
value structure.
* buffer.c (PER_BUFFER_SYMBOL): Move from buffer.h.
(clone_per_buffer_values): Only adjust markers into the current buffer.
(reset_buffer_local_variables): PER_BUFFER_IDX is never -2.
(Fbuffer_local_value, set_buffer_internal_1)
(swap_out_buffer_local_variables):
Adapt to the new symbol value structure.
(DEFVAR_PER_BUFFER): Allocate a Lisp_Buffer_Objfwd object.
(defvar_per_buffer): Take a new arg for the fwd object.
(buffer_lisp_local_variables): Return a proper alist (different fix
for bug#4138).
* alloc.c (Fmake_symbol): Use SET_SYMBOL_VAL.
(Fgarbage_collect): Don't handle buffer_defaults specially.
(mark_object): Handle new symbol value structure rather than the old
special Lisp_Misc_* objects.
(gc_sweep) <symbols>: Free also the buffer-local-value objects.
* term.c (set_tty_color_mode):
* bidi.c (bidi_initialize): Don't access the ->value field directly.
* buffer.h (PER_BUFFER_VAR_OFFSET): Don't bother with
a buffer_local_flags.
* print.c (print_object): Get rid of impossible forwarding objects.
author | Stefan Monnier <monnier@iro.umontreal.ca> |
---|---|
date | Mon, 19 Apr 2010 21:50:52 -0400 |
parents | 1d1d5d9bd884 |
children | f1266b2f017e |
line wrap: on
line source
\input texinfo @c -*-texinfo-*- @setfilename ../../info/sasl @set VERSION 0.2 @settitle Emacs SASL Library @value{VERSION} @copying This file describes the Emacs SASL library, version @value{VERSION}. Copyright @copyright{} 2000, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License'' in the Emacs manual. (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.'' This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license. @end quotation @end copying @dircategory Emacs @direntry * SASL: (sasl). The Emacs SASL library. @end direntry @titlepage @title Emacs SASL Library @value{VERSION} @author by Daiki Ueno @page @vskip 0pt plus 1filll @insertcopying @end titlepage @node Top @top Emacs SASL SASL is a common interface to share several authentication mechanisms between applications using different protocols. @ifnottex @insertcopying @end ifnottex @menu * Overview:: What Emacs SASL library is. * How to use:: Adding authentication support to your applications. * Data types:: * Back end drivers:: Writing your own drivers. * Index:: * Function Index:: * Variable Index:: @end menu @node Overview @chapter Overview @sc{sasl} is short for @dfn{Simple Authentication and Security Layer}. This standard is documented in RFC2222. It provides a simple method for adding authentication support to various application protocols. The toplevel interface of this library is inspired by Java @sc{sasl} Application Program Interface. It defines an abstraction over a series of authentication mechanism drivers (@ref{Back end drivers}). Back end drivers are designed to be close as possible to the authentication mechanism. You can access the additional configuration information anywhere from the implementation. @node How to use @chapter How to use (Not yet written). To use Emacs SASL library, please evaluate following expression at the beginning of your application program. @lisp (require 'sasl) @end lisp If you want to check existence of sasl.el at runtime, instead you can list autoload settings for functions you want. @node Data types @chapter Data types There are three data types to be used for carrying a negotiated security layer---a mechanism, a client parameter and an authentication step. @menu * Mechanisms:: * Clients:: * Steps:: @end menu @node Mechanisms @section Mechanisms A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl} authentication mechanism driver. @defvar sasl-mechanisms A list of mechanism names. @end defvar @defun sasl-find-mechanism mechanisms Retrieve an appropriate mechanism. This function compares @var{mechanisms} and @code{sasl-mechanisms} then returns appropriate @code{sasl-mechanism} object. @example (let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5"))) (setq mechanism (sasl-find-mechanism server-supported-mechanisms))) @end example @end defun @defun sasl-mechanism-name mechanism Return name of mechanism, a string. @end defun If you want to write an authentication mechanism driver (@ref{Back end drivers}), use @code{sasl-make-mechanism} and modify @code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly. @defun sasl-make-mechanism name steps Allocate a @code{sasl-mechanism} object. This function takes two parameters---name of the mechanism, and a list of authentication functions. @example (defconst sasl-anonymous-steps '(identity ;no initial response sasl-anonymous-response)) (put 'sasl-anonymous 'sasl-mechanism (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps)) @end example @end defun @node Clients @section Clients A client (@code{sasl-client} object) initialized with four parameters---a mechanism, a user name, name of the service and name of the server. @defun sasl-make-client mechanism name service server Prepare a @code{sasl-client} object. @end defun @defun sasl-client-mechanism client Return the mechanism (@code{sasl-mechanism} object) of client. @end defun @defun sasl-client-name client Return the authorization name of client, a string. @end defun @defun sasl-client-service client Return the service name of client, a string. @end defun @defun sasl-client-server client Return the server name of client, a string. @end defun If you want to specify additional configuration properties, please use @code{sasl-client-set-property}. @defun sasl-client-set-property client property value Add the given property/value to client. @end defun @defun sasl-client-property client property Return the value of the property of client. @end defun @defun sasl-client-set-properties client plist Destructively set the properties of client. The second argument is the new property list. @end defun @defun sasl-client-properties client Return the whole property list of client configuration. @end defun @node Steps @section Steps A step (@code{sasl-step} object) is an abstraction of authentication ``step'' which holds the response value and the next entry point for the authentication process (the latter is not accessible). @defun sasl-step-data step Return the data which @var{step} holds, a string. @end defun @defun sasl-step-set-data step data Store @var{data} string to @var{step}. @end defun To get the initial response, you should call the function @code{sasl-next-step} with the second argument @code{nil}. @example (setq name (sasl-mechanism-name mechanism)) @end example At this point we could send the command which starts a SASL authentication protocol exchange. For example, @example (process-send-string process (if (sasl-step-data step) ;initial response (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t)) (format "AUTH %s\r\n" name))) @end example To go on with the authentication process, all you have to do is call @code{sasl-next-step} consecutively. @defun sasl-next-step client step Perform the authentication step. At the first time @var{step} should be set to @code{nil}. @end defun @node Back end drivers @chapter Back end drivers (Not yet written). @node Index @chapter Index @printindex cp @node Function Index @chapter Function Index @printindex fn @node Variable Index @chapter Variable Index @printindex vr @summarycontents @contents @bye @c End: @ignore arch-tag: dc9650be-a953-40bf-bc55-24fe5f19d875 @end ignore