Add notes regarding alternatives to deprecated routines

diff --git a/include/ldap.h b/include/ldap.h
index c6a3fcf2dc67e95ad7f9009e62357a477fc0452d..def08f7d496e5cb72d19a3dc9d996ea4ea4e8204 100644 (file)
--- a/include/ldap.h
+++ b/include/ldap.h
@@ -888,9 +888,9 @@ ldap_abandon_ext LDAP_P((
        LDAPControl             **serverctrls,
        LDAPControl             **clientctrls ));
 
-#if LDAP_DEPRECATED
+#if LDAP_DEPRECATED    
 LDAP_F( int )
-ldap_abandon LDAP_P((  /* deprecated */
+ldap_abandon LDAP_P((  /* deprecated, use ldap_abandon_ext */
        LDAP *ld,
        int msgid ));
 #endif
@@ -917,13 +917,13 @@ ldap_add_ext_s LDAP_P((
 
 #if LDAP_DEPRECATED
 LDAP_F( int )
-ldap_add LDAP_P((      /* deprecated */
+ldap_add LDAP_P((      /* deprecated, use ldap_add_ext */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAPMod **attrs ));
 
 LDAP_F( int )
-ldap_add_s LDAP_P((    /* deprecated */
+ldap_add_s LDAP_P((    /* deprecated, use ldap_add_ext_s */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAPMod **attrs ));
@@ -996,14 +996,14 @@ ldap_parse_sasl_bind_result LDAP_P((
  *     (deprecated)
  */
 LDAP_F( int )
-ldap_bind LDAP_P((     /* deprecated */
+ldap_bind LDAP_P((     /* deprecated, use ldap_sasl_bind */
        LDAP *ld,
        LDAP_CONST char *who,
        LDAP_CONST char *passwd,
        int authmethod ));
 
 LDAP_F( int )
-ldap_bind_s LDAP_P((   /* deprecated */
+ldap_bind_s LDAP_P((   /* deprecated, use ldap_sasl_bind_s */
        LDAP *ld,
        LDAP_CONST char *who,
        LDAP_CONST char *cred,
@@ -1013,13 +1013,13 @@ ldap_bind_s LDAP_P((    /* deprecated */
  * in sbind.c:
  */
 LDAP_F( int )
-ldap_simple_bind LDAP_P(( /* deprecated */
+ldap_simple_bind LDAP_P(( /* deprecated, use ldap_sasl_bind */
        LDAP *ld,
        LDAP_CONST char *who,
        LDAP_CONST char *passwd ));
 
 LDAP_F( int )
-ldap_simple_bind_s LDAP_P(( /* deprecated */
+ldap_simple_bind_s LDAP_P(( /* deprecated, use ldap_sasl_bind_s */
        LDAP *ld,
        LDAP_CONST char *who,
        LDAP_CONST char *passwd ));
@@ -1027,7 +1027,7 @@ ldap_simple_bind_s LDAP_P(( /* deprecated */
 
 /*
  * in kbind.c:
- *     (deprecated)
+ *     (deprecated - use SASL instead)
  */
 LDAP_F( int )
 ldap_kerberos_bind_s LDAP_P((  /* deprecated */
@@ -1080,14 +1080,14 @@ ldap_compare_ext_s LDAP_P((
 
 #if LDAP_DEPRECATED
 LDAP_F( int )
-ldap_compare LDAP_P((  /* deprecated */
+ldap_compare LDAP_P((  /* deprecated, use ldap_compare_ext */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAP_CONST char *attr,
        LDAP_CONST char *value ));
 
 LDAP_F( int )
-ldap_compare_s LDAP_P((        /* deprecated */
+ldap_compare_s LDAP_P((        /* deprecated, use ldap_compare_ext_s */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAP_CONST char *attr,
@@ -1115,12 +1115,12 @@ ldap_delete_ext_s LDAP_P((
 
 #if LDAP_DEPRECATED
 LDAP_F( int )
-ldap_delete LDAP_P((   /* deprecated */
+ldap_delete LDAP_P((   /* deprecated, use ldap_delete_ext */
        LDAP *ld,
        LDAP_CONST char *dn ));
 
 LDAP_F( int )
-ldap_delete_s LDAP_P(( /* deprecated */
+ldap_delete_s LDAP_P(( /* deprecated, use ldap_delete_ext_s */
        LDAP *ld,
        LDAP_CONST char *dn ));
 #endif
@@ -1146,13 +1146,13 @@ ldap_err2string LDAP_P((
 
 #if LDAP_DEPRECATED
 LDAP_F( int )
-ldap_result2error LDAP_P((     /* deprecated */
+ldap_result2error LDAP_P((     /* deprecated, use ldap_parse_result */
        LDAP *ld,
        LDAPMessage *r,
        int freeit ));
 
 LDAP_F( void )
-ldap_perror LDAP_P((   /* deprecated */
+ldap_perror LDAP_P((   /* deprecated, use ldap_err2string */
        LDAP *ld,
        LDAP_CONST char *s ));
 #endif
@@ -1180,13 +1180,13 @@ ldap_modify_ext_s LDAP_P((
 
 #if LDAP_DEPRECATED
 LDAP_F( int )
-ldap_modify LDAP_P((   /* deprecated */
+ldap_modify LDAP_P((   /* deprecated, use ldap_modify_ext */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAPMod **mods ));
 
 LDAP_F( int )
-ldap_modify_s LDAP_P(( /* deprecated */
+ldap_modify_s LDAP_P(( /* deprecated, use ldap_modify_ext_s */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAPMod **mods ));
@@ -1219,7 +1219,7 @@ ldap_rename_s LDAP_P((
 
 #if LDAP_DEPRECATED
 LDAP_F( int )
-ldap_rename2 LDAP_P((  /* deprecated */
+ldap_rename2 LDAP_P((  /* deprecated, use ldap_rename */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAP_CONST char *newrdn,
@@ -1227,7 +1227,7 @@ ldap_rename2 LDAP_P((     /* deprecated */
        int deleteoldrdn ));
 
 LDAP_F( int )
-ldap_rename2_s LDAP_P((        /* deprecated */
+ldap_rename2_s LDAP_P((        /* deprecated, use ldap_rename_s */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAP_CONST char *newrdn,
@@ -1235,26 +1235,26 @@ ldap_rename2_s LDAP_P(( /* deprecated */
        int deleteoldrdn ));
 
 LDAP_F( int )
-ldap_modrdn LDAP_P((   /* deprecated */
+ldap_modrdn LDAP_P((   /* deprecated, use ldap_rename */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAP_CONST char *newrdn ));
 
 LDAP_F( int )
-ldap_modrdn_s LDAP_P(( /* deprecated */
+ldap_modrdn_s LDAP_P(( /* deprecated, use ldap_rename_s */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAP_CONST char *newrdn ));
 
 LDAP_F( int )
-ldap_modrdn2 LDAP_P((  /* deprecated */
+ldap_modrdn2 LDAP_P((  /* deprecated, use ldap_rename */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAP_CONST char *newrdn,
        int deleteoldrdn ));
 
 LDAP_F( int )
-ldap_modrdn2_s LDAP_P((        /* deprecated */
+ldap_modrdn2_s LDAP_P((        /* deprecated, use ldap_rename_s */
        LDAP *ld,
        LDAP_CONST char *dn,
        LDAP_CONST char *newrdn,
@@ -1267,12 +1267,12 @@ ldap_modrdn2_s LDAP_P(( /* deprecated */
  */
 #if LDAP_DEPRECATED
 LDAP_F( LDAP * )
-ldap_init LDAP_P(( /* deprecated */
+ldap_init LDAP_P(( /* deprecated, use ldap_create or ldap_initialize */
        LDAP_CONST char *host,
        int port ));
 
 LDAP_F( LDAP * )
-ldap_open LDAP_P((     /* deprecated */
+ldap_open LDAP_P((     /* deprecated, use ldap_create or ldap_initialize */
        LDAP_CONST char *host,
        int port ));
 #endif
@@ -1496,16 +1496,16 @@ ldap_dn_normalize LDAP_P((
        char **out, unsigned oflags ));
 
 LDAP_F( char * )
-ldap_dn2ufn LDAP_P(( /* deprecated */
+ldap_dn2ufn LDAP_P(( /* deprecated, use ldap_str2dn/dn2str */
        LDAP_CONST char *dn ));
 
 LDAP_F( char ** )
-ldap_explode_dn LDAP_P(( /* deprecated */
+ldap_explode_dn LDAP_P(( /* deprecated, ldap_str2dn */
        LDAP_CONST char *dn,
        int notypes ));
 
 LDAP_F( char ** )
-ldap_explode_rdn LDAP_P(( /* deprecated */
+ldap_explode_rdn LDAP_P(( /* deprecated, ldap_str2rdn */
        LDAP_CONST char *rdn,
        int notypes ));
 
@@ -1517,13 +1517,16 @@ ldap_X509dn2bv LDAP_P(( void *x509_name, struct berval *dn,
        LDAPDN_rewrite_func *func, unsigned flags ));
 
 LDAP_F( char * )
-ldap_dn2dcedn LDAP_P(( LDAP_CONST char *dn )); /* deprecated */
+ldap_dn2dcedn LDAP_P(( /* deprecated, ldap_str2dn/dn2str */
+       LDAP_CONST char *dn ));
 
 LDAP_F( char * )
-ldap_dcedn2dn LDAP_P(( LDAP_CONST char *dce ));        /* deprecated */
+ldap_dcedn2dn LDAP_P(( /* deprecated, ldap_str2dn/dn2str */
+       LDAP_CONST char *dce ));
 
 LDAP_F( char * )
-ldap_dn2ad_canonical LDAP_P(( LDAP_CONST char *dn ));  /* deprecated */
+ldap_dn2ad_canonical LDAP_P(( /* deprecated, ldap_str2dn/dn2str */
+       LDAP_CONST char *dn ));
 
 LDAP_F( int )
 ldap_get_dn_ber LDAP_P((
@@ -1569,17 +1572,17 @@ ldap_value_free_len LDAP_P((
 
 #if LDAP_DEPRECATED
 LDAP_F( char ** )
-ldap_get_values LDAP_P((       /* deprecated */
+ldap_get_values LDAP_P((       /* deprecated, use ldap_get_values_len */
        LDAP *ld,
        LDAPMessage *entry,
        LDAP_CONST char *target ));
 
 LDAP_F( int )
-ldap_count_values LDAP_P((     /* deprecated */
+ldap_count_values LDAP_P((     /* deprecated, use ldap_count_values_len */
        char **vals ));
 
 LDAP_F( void )
-ldap_value_free LDAP_P((       /* deprecated */
+ldap_value_free LDAP_P((       /* deprecated, use ldap_values_free_len */
        char **vals ));
 #endif
 
@@ -1650,7 +1653,7 @@ ldap_search_ext_s LDAP_P((
 
 #if LDAP_DEPRECATED
 LDAP_F( int )
-ldap_search LDAP_P((   /* deprecated */
+ldap_search LDAP_P((   /* deprecated, use ldap_search_ext */
        LDAP *ld,
        LDAP_CONST char *base,
        int scope,
@@ -1659,7 +1662,7 @@ ldap_search LDAP_P((      /* deprecated */
        int attrsonly ));
 
 LDAP_F( int )
-ldap_search_s LDAP_P(( /* deprecated */
+ldap_search_s LDAP_P(( /* deprecated, use ldap_search_ext_s */
        LDAP *ld,
        LDAP_CONST char *base,
        int scope,
@@ -1669,7 +1672,7 @@ ldap_search_s LDAP_P((    /* deprecated */
        LDAPMessage **res ));
 
 LDAP_F( int )
-ldap_search_st LDAP_P((        /* deprecated */
+ldap_search_st LDAP_P((        /* deprecated, use ldap_search_ext_s */
        LDAP *ld,
        LDAP_CONST char *base,
        int scope,
@@ -1697,11 +1700,11 @@ ldap_unbind_ext_s LDAP_P((
 
 #if LDAP_DEPRECATED
 LDAP_F( int )
-ldap_unbind LDAP_P(( /* deprecated */
+ldap_unbind LDAP_P(( /* deprecated, use ldap_bind_ext */
        LDAP *ld ));
 
 LDAP_F( int )
-ldap_unbind_s LDAP_P(( /* deprecated */
+ldap_unbind_s LDAP_P(( /* deprecated, use ldap_bind_ext_s */
        LDAP *ld ));
 #endif
 
@@ -1751,7 +1754,7 @@ ldap_mods_free LDAP_P((
 
 #if LDAP_DEPRECATED
 /*
- * in sort.c (deprecated)
+ * in sort.c (deprecated, use custom code instead)
  */
 typedef int (LDAP_SORT_AD_CMP_PROC) LDAP_P(( /* deprecated */
        LDAP_CONST char *left,
@@ -1872,6 +1875,7 @@ ldap_create_page_control LDAP_P((
 #if LDAP_DEPRECATED
 LDAP_F( int )
 ldap_parse_page_control LDAP_P((
+       /* deprecated, use ldap_parse_pageresponse_control */
        LDAP *ld,
        LDAPControl **ctrls,
        ber_int_t *count,