git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_charset.3

   1 .TH LDAP_CHARSET 3  "28 March 1996" "U-M LDAP LDVERSION"
   2 .SH NAME
   3 ldap_set_string_translators,
   4 ldap_t61_to_8859,
   5 ldap_8859_to_t61,
   6 ldap_translate_from_t61,
   7 ldap_translate_to_t61,
   8 ldap_enable_translation \- LDAP character set translation routines
   9 .SH SYNOPSIS
  10 .nf
  11 .ft B
  12 #include <lber.h>
  13 #include <ldap.h>
  14 .ft
  15 .LP
  16 .ft B
  17 void ldap_set_string_translators( ld, encode_proc, decode_proc )
  18 .ft
  19 LDAP                    *ld;
  20 BERTranslateProc        encode_proc;
  21 BERTranslateProc        decode_proc;
  22 .LP
  23 .ft B
  24 typedef int (*BERTranslateProc)( char **bufp, unsigned long *buflenp,
  25         int free_input );
  26 .ft
  27 .LP
  28 .ft B
  29 int ldap_t61_to_8859( bufp, buflenp, free_input )
  30 .ft
  31 char            **bufp;
  32 unsigned long   *buflenp;
  33 int             free_input;
  34 .LP
  35 .ft B
  36 int ldap_8859_to_t61( bufp, buflenp, free_input )
  37 .ft
  38 char            **bufp;
  39 unsigned long   *buflenp;
  40 int             free_input;
  41 .LP
  42 .ft B
  43 int ldap_translate_from_t61( ld, bufp, lenp, free_input )
  44 .ft
  45 LDAP            *ld;
  46 char            **bufp;
  47 unsigned long   *lenp;
  48 int             free_input;
  49 .LP
  50 .ft B
  51 int ldap_translate_to_t61( ld, bufp, lenp, free_input )
  52 .ft
  53 LDAP            *ld;
  54 char            **bufp;
  55 unsigned long   *lenp;
  56 int             free_input;
  57 .LP
  58 .ft B
  59 void ldap_enable_translation( ld, entry, enable )
  60 .ft
  61 LDAP            *ld;
  62 LDAPMessage     *entry;
  63 int             enable;
  64 .fi
  65 .SH DESCRIPTION
  66 .LP
  67 These routines are used to used to enable translation of character strings
  68 used in the LDAP library to and from the T.61 character set used in the
  69 LDAP protocol.  These functions are only available if the LDAP and LBER
  70 libraries are compiled with STR_TRANSLATION defined.
  71 It is also possible to turn on character translation by default so that
  72 all LDAP library callers will experience translation; see the LDAP
  73 Make-common source file for details.
  74 .LP
  75 .B ldap_set_string_translators()
  76 sets the translation routines that will
  77 be used by the LDAP library.  They are not actually used until the
  78 \fIld_lberoptions\fP field of the LDAP structure is set to include the
  79 LBER_TRANSLATE_STRINGS option.
  80 .LP
  81 .B ldap_t61_to_8859()
  82 and
  83 .B ldap_8859_to_t61()
  84 are translation routines for
  85 converting between T.61 characters and ISO-8859 characters.  The specific
  86 8859 character set used is determined at compile time.
  87 .LP
  88 .B ldap_translate_from_t61()
  89 is used to translate a string of characters from the T.61 character set to a
  90 different character set.  The actual translation is done using the
  91 \fIdecode_proc\fP that was passed to a previous call to
  92 .B ldap_set_string_translators().
  93 On entry, \fI*bufp\fP should point to the start of the T.61 characters
  94 to be translated and \fI*lenp\fP should contain the number of bytes to
  95 translate.  If \fIfree_input\fP is non-zero, the input buffer will be
  96 freed if translation is a success.  If the translation is a success,
  97 LDAP_SUCCESS will be returned, \fI*bufp\fP will point to a newly
  98 malloc'd buffer that contains the translated characters, and
  99 \fI*lenp\fP will contain the length of the result.  If translation
 100 fails, an LDAP error code will be returned.
 101
 102 .LP
 103 .B ldap_translate_to_t61()
 104 is used to translate a string of characters to the T.61 character set from a
 105 different character set.  The actual translation is done using the
 106 \fIencode_proc\fP that was passed to a previous call to
 107 .B ldap_set_string_translators().
 108 This function is called just like
 109 .B ldap_translate_from_t61().
 110 .LP
 111 .B ldap_enable_translation()
 112 is used to turn on or off string translation for the LDAP entry \fIentry\fP
 113 (typically obtained by calling
 114 .B ldap_first_entry()
 115 or
 116 .B ldap_next_entry()
 117 after a successful LDAP search operation).  If \fIenable\fP is zero,
 118 translation is disabled; if non-zero, translation is enabled.  This routine
 119 is useful if you need to ensure that a particular attribute is not
 120 translated when it is extracted using
 121 .B ldap_get_values()
 122 or
 123 .B ldap_get_values_len().
 124 For example, you would not want to translate a binary attributes such as
 125 jpegPhoto.
 126 .SH SEE ALSO
 127 .BR ldap (3)