home *** CD-ROM | disk | FTP | other *** search
/ PC Plus SuperCD (UK) 2000 May / PCP163A.iso / Runimage / Cbuilder4 / Include / WINLDAP.H < prev    next >
Encoding:
C/C++ Source or Header  |  1999-01-26  |  84.9 KB  |  2,796 lines
  1. /*++
  2.  
  3. Copyright (c) 1996  Microsoft Corporation
  4.  
  5. Module Name:
  6.  
  7.     winldap.h   LDAP client 32 API header file
  8.  
  9. Abstract:
  10.  
  11.    This module is the header file for the 32 bit LDAP client API for
  12.    Windows NT and Windows 95.  This API is based on RFC 1823 with some
  13.    enhancements for LDAP v3.
  14.  
  15.    Notes about Unicode support :
  16.  
  17.    If you have UNICODE defined at compile time, you'll pull in the unicode
  18.    versions of the calls.  Note that your executable may then not work with
  19.    other implementations of the LDAP API that don't support Unicode.  If
  20.    UNICODE is not defined, then we define the LDAP calls without the trailing
  21.    'A' (as in ldap_bind rather than ldap_bindA) so that your app may work
  22.    with other implementations that don't support Unicode.
  23.  
  24.    The import library has all three forms of the call present... ldap_bindW,
  25.    ldap_bindA, and ldap_bind.  ldap_bindA simply calls ldap_bind.  ldap_bind
  26.    simply converts the arguments to unicode and calls ldap_bindW.  The
  27.    reason this is done is because we have to put UTF-8 on the wire, so if
  28.    we converted from Unicode to single byte, we'd loose information.  Since
  29.    all core processing is done in Unicode, nothing is lost.
  30.  
  31. Updates :
  32.  
  33.    11/01/96  Modified for new API RFC draft.
  34.  
  35. Environments :
  36.  
  37.     Win32 user mode
  38.  
  39. --*/
  40.  
  41. //
  42. //  Only pull in this header file once... controlled by LDAP_CLIENT_DEFINED
  43. //  variable.
  44. //
  45.  
  46. #ifndef LDAP_CLIENT_DEFINED
  47. #pragma option push -b -a8 -pc -A- /*P_O_Push_S*/
  48. #define LDAP_CLIENT_DEFINED
  49.  
  50. #ifdef __cplusplus
  51. extern "C" {
  52. #endif
  53.  
  54. #ifndef BASETYPES
  55. #include <windef.h>
  56. #endif
  57.  
  58. #if !defined(_WINLDAP_)
  59. #define WINLDAPAPI DECLSPEC_IMPORT
  60. #else
  61. #define WINLDAPAPI __declspec(dllexport)
  62. #endif
  63.  
  64. #ifndef LDAPAPI
  65. #define LDAPAPI __cdecl
  66. #endif
  67.  
  68. //
  69. //  The #define LDAP_UNICODE controls if we map the undecorated calls to
  70. //  their unicode counterparts or just leave them defined as the normal
  71. //  single byte entry points.
  72. //
  73. //  If you want to write a UNICODE enabled application, you'd normally
  74. //  just have UNICODE defined and then we'll default to using all LDAP
  75. //  Unicode calls.
  76. //
  77.  
  78. #ifndef LDAP_UNICODE
  79. #ifdef UNICODE
  80. #define LDAP_UNICODE 1
  81. #else
  82. #define LDAP_UNICODE 0
  83. #endif
  84. #endif
  85.  
  86. //
  87. //  Global constants
  88. //
  89.  
  90. #define LDAP_PORT               389
  91. #define LDAP_SSL_PORT           636
  92.  
  93. //
  94. //  We currently support going to either v2 or v3 servers, though the API
  95. //  is only a V2 API.  We'll add support for result sets, server side
  96. //  sorting, extended operations, etc as soon as they stabilize.
  97. //
  98.  
  99. #define LDAP_VERSION1           1
  100. #define LDAP_VERSION2           2
  101. #define LDAP_VERSION3           3
  102. #define LDAP_VERSION            LDAP_VERSION2
  103.  
  104. //
  105. //  All tags are CCFTTTTT.
  106. //               CC        Tag Class 00 = universal
  107. //                                   01 = application wide
  108. //                                   10 = context specific
  109. //                                   11 = private use
  110. //
  111. //                 F       Form 0 primitive
  112. //                              1 constructed
  113. //
  114. //                  TTTTT  Tag Number
  115. //
  116.  
  117. //
  118. // LDAP v2 & v3 commands.
  119. //
  120.  
  121. #define LDAP_BIND_CMD           0x60L   // application + constructed
  122. #define LDAP_UNBIND_CMD         0x42L   // application + primitive
  123. #define LDAP_SEARCH_CMD         0x63L   // application + constructed
  124. #define LDAP_MODIFY_CMD         0x66L   // application + constructed
  125. #define LDAP_ADD_CMD            0x68L   // application + constructed
  126. #define LDAP_DELETE_CMD         0x4aL   // application + primitive
  127. #define LDAP_MODRDN_CMD         0x6cL   // application + constructed
  128. #define LDAP_COMPARE_CMD        0x6eL   // application + constructed
  129. #define LDAP_ABANDON_CMD        0x50L   // application + primitive
  130. #define LDAP_SESSION_CMD        0x71L   // not in base LDAP protocol
  131. #define LDAP_EXTENDED_CMD       0x77L   // application + constructed
  132.  
  133. //
  134. // Responses/Results for LDAP v2 & v3
  135. //
  136.  
  137. #define LDAP_RES_BIND           0x61L   // application + constructed
  138. #define LDAP_RES_SEARCH_ENTRY   0x64L   // application + constructed
  139. #define LDAP_RES_SEARCH_RESULT  0x65L   // application + constructed
  140. #define LDAP_RES_MODIFY         0x67L   // application + constructed
  141. #define LDAP_RES_ADD            0x69L   // application + constructed
  142. #define LDAP_RES_DELETE         0x6bL   // application + constructed
  143. #define LDAP_RES_MODRDN         0x6dL   // application + constructed
  144. #define LDAP_RES_COMPARE        0x6fL   // application + constructed
  145. #define LDAP_RES_SESSION        0x72L   // not in base LDAP protocol
  146. #define LDAP_RES_REFERRAL       0x73L   // application + constructed
  147. #define LDAP_RES_EXTENDED       0x78L   // application + constructed
  148. #define LDAP_RES_ANY            (-1L)
  149.  
  150. #define LDAP_INVALID_CMD         0xff
  151. #define LDAP_INVALID_RES         0xff
  152.  
  153.  
  154. //
  155. // We'll make the error codes compatible with reference implementation
  156. //
  157.  
  158. typedef enum {
  159.     LDAP_SUCCESS                    =   0x00,
  160.     LDAP_OPERATIONS_ERROR           =   0x01,
  161.     LDAP_PROTOCOL_ERROR             =   0x02,
  162.     LDAP_TIMELIMIT_EXCEEDED         =   0x03,
  163.     LDAP_SIZELIMIT_EXCEEDED         =   0x04,
  164.     LDAP_COMPARE_FALSE              =   0x05,
  165.     LDAP_COMPARE_TRUE               =   0x06,
  166.     LDAP_AUTH_METHOD_NOT_SUPPORTED  =   0x07,
  167.     LDAP_STRONG_AUTH_REQUIRED       =   0x08,
  168.     LDAP_REFERRAL_V2                =   0x09,
  169.     LDAP_PARTIAL_RESULTS            =   0x09,
  170.     LDAP_REFERRAL                   =   0x0a,
  171.     LDAP_ADMIN_LIMIT_EXCEEDED       =   0x0b,
  172.     LDAP_UNAVAILABLE_CRIT_EXTENSION =   0x0c,
  173.     LDAP_CONFIDENTIALITY_REQUIRED   =   0x0d,
  174.  
  175.     LDAP_NO_SUCH_ATTRIBUTE          =   0x10,
  176.     LDAP_UNDEFINED_TYPE             =   0x11,
  177.     LDAP_INAPPROPRIATE_MATCHING     =   0x12,
  178.     LDAP_CONSTRAINT_VIOLATION       =   0x13,
  179.     LDAP_ATTRIBUTE_OR_VALUE_EXISTS  =   0x14,
  180.     LDAP_INVALID_SYNTAX             =   0x15,
  181.  
  182.     LDAP_NO_SUCH_OBJECT             =   0x20,
  183.     LDAP_ALIAS_PROBLEM              =   0x21,
  184.     LDAP_INVALID_DN_SYNTAX          =   0x22,
  185.     LDAP_IS_LEAF                    =   0x23,
  186.     LDAP_ALIAS_DEREF_PROBLEM        =   0x24,
  187.  
  188.     LDAP_INAPPROPRIATE_AUTH         =   0x30,
  189.     LDAP_INVALID_CREDENTIALS        =   0x31,
  190.     LDAP_INSUFFICIENT_RIGHTS        =   0x32,
  191.     LDAP_BUSY                       =   0x33,
  192.     LDAP_UNAVAILABLE                =   0x34,
  193.     LDAP_UNWILLING_TO_PERFORM       =   0x35,
  194.     LDAP_LOOP_DETECT                =   0x36,
  195.  
  196.     LDAP_NAMING_VIOLATION           =   0x40,
  197.     LDAP_OBJECT_CLASS_VIOLATION     =   0x41,
  198.     LDAP_NOT_ALLOWED_ON_NONLEAF     =   0x42,
  199.     LDAP_NOT_ALLOWED_ON_RDN         =   0x43,
  200.     LDAP_ALREADY_EXISTS             =   0x44,
  201.     LDAP_NO_OBJECT_CLASS_MODS       =   0x45,
  202.     LDAP_RESULTS_TOO_LARGE          =   0x46,
  203.     LDAP_AFFECTS_MULTIPLE_DSAS      =   0x47,
  204.  
  205.     LDAP_OTHER                      =   0x50,
  206.     LDAP_SERVER_DOWN                =   0x51,
  207.     LDAP_LOCAL_ERROR                =   0x52,
  208.     LDAP_ENCODING_ERROR             =   0x53,
  209.     LDAP_DECODING_ERROR             =   0x54,
  210.     LDAP_TIMEOUT                    =   0x55,
  211.     LDAP_AUTH_UNKNOWN               =   0x56,
  212.     LDAP_FILTER_ERROR               =   0x57,
  213.     LDAP_USER_CANCELLED             =   0x58,
  214.     LDAP_PARAM_ERROR                =   0x59,
  215.     LDAP_NO_MEMORY                  =   0x5a,
  216.     LDAP_CONNECT_ERROR              =   0x5b,
  217.     LDAP_NOT_SUPPORTED              =   0x5c,
  218.     LDAP_NO_RESULTS_RETURNED        =   0x5e,
  219.     LDAP_CONTROL_NOT_FOUND          =   0x5d,
  220.     LDAP_MORE_RESULTS_TO_RETURN     =   0x5f,
  221.  
  222.     LDAP_CLIENT_LOOP                =   0x60,
  223.     LDAP_REFERRAL_LIMIT_EXCEEDED    =   0x61
  224. } LDAP_RETCODE;
  225.  
  226. //
  227. //  Bind methods.  We support the following methods :
  228. //
  229. //      Simple         Clear text password... try not to use as it's not secure.
  230. //
  231. //      MSN            MSN (Microsoft Network) authentication. This package
  232. //                     may bring up UI to prompt the user for MSN credentials.
  233. //
  234. //      DPA            Normandy authentication... new MSN authentication.  Same
  235. //                     usage as MSN.
  236. //
  237. //      NTLM           NT domain authentication.  Use NULL credentials and
  238. //                     we'll try to use default logged in user credentials.
  239. //
  240. //      Sicily         Negotiate with the server for any of: MSN, DPA, NTLM
  241. //                     Should be used for LDAPv2 servers only.
  242. //
  243. //      Negotiate      Use GSSAPI Negotiate package to negotiate security
  244. //                     package of either Kerberos v5 or NTLM (or any other
  245. //                     package the client and server negotiate).  Pass in
  246. //                     NULL credentials to specify default logged in user.
  247. //                     If Negotiate package is not installed on server or
  248. //                     client, this will fall back to Sicily negotiation.
  249. //
  250. //  For all bind methods except for Simple, you may pass in a
  251. //  SEC_WINNT_AUTH_IDENTITY_W (defined in rpcdce.h) to specify alternate
  252. //  credentials.
  253. //
  254. //  All bind methods other than simple are synchronous only calls.
  255. //  Calling the asynchronous bind call for any of these messages will
  256. //  return LDAP_PARAM_ERROR.
  257. //
  258. //  Using any other method besides simple will cause WLDAP32 to pull in
  259. //  the SSPI security DLLs (SECURITY.DLL etc).
  260. //
  261. //  On non-Simple methods, if you specify NULL credentials, we'll attempt to use
  262. //  the default logged in user.
  263. //
  264.  
  265. #define LDAP_AUTH_SIMPLE                0x80L
  266. #define LDAP_AUTH_SASL                  0x83L   // don't use... should go away
  267.  
  268. #define LDAP_AUTH_OTHERKIND             0x86L
  269.  
  270. // The SICILY type covers package negotiation to MSN servers.
  271. // Each of the supported types can also be specified without
  272. // doing the package negotiation, assuming the caller knows
  273. // what the server supports.
  274.  
  275. #define LDAP_AUTH_SICILY                (LDAP_AUTH_OTHERKIND | 0x0200)
  276.  
  277. #define LDAP_AUTH_MSN                   (LDAP_AUTH_OTHERKIND | 0x0800)
  278. #define LDAP_AUTH_NTLM                  (LDAP_AUTH_OTHERKIND | 0x1000)
  279. #define LDAP_AUTH_DPA                   (LDAP_AUTH_OTHERKIND | 0x2000)
  280.  
  281. // This will cause the client to use the GSSAPI negotiation
  282. // package to determine the most appropriate authentication type.
  283. // This type should be used when talking to NT5.
  284.  
  285. #define LDAP_AUTH_NEGOTIATE             (LDAP_AUTH_OTHERKIND | 0x0400)
  286.  
  287. // backward compatible #define for older constant name.
  288.  
  289. #define LDAP_AUTH_SSPI                   LDAP_AUTH_NEGOTIATE
  290.  
  291. //
  292. //  Client applications typically don't have to encode/decode LDAP filters,
  293. //  but if they do, we define the operators here.
  294. //
  295. //  Filter types.
  296.  
  297. #define LDAP_FILTER_AND         0xa0    // context specific + constructed - SET OF Filters.
  298. #define LDAP_FILTER_OR          0xa1    // context specific + constructed - SET OF Filters.
  299. #define LDAP_FILTER_NOT         0xa2    // context specific + constructed - Filter
  300. #define LDAP_FILTER_EQUALITY    0xa3    // context specific + constructed - AttributeValueAssertion.
  301. #define LDAP_FILTER_SUBSTRINGS  0xa4    // context specific + constructed - SubstringFilter
  302. #define LDAP_FILTER_GE          0xa5    // context specific + constructed - AttributeValueAssertion.
  303. #define LDAP_FILTER_LE          0xa6    // context specific + constructed - AttributeValueAssertion.
  304. #define LDAP_FILTER_PRESENT     0x87    // context specific + primitive   - AttributeType.
  305. #define LDAP_FILTER_APPROX      0xa8    // context specific + constructed - AttributeValueAssertion.
  306.  
  307. //  Substring filter types
  308.  
  309. #define LDAP_SUBSTRING_INITIAL  0x80L   // class context specific
  310. #define LDAP_SUBSTRING_ANY      0x81L   // class context specific
  311. #define LDAP_SUBSTRING_FINAL    0x82L   // class context specific
  312.  
  313. //
  314. //  Possible values for ld_deref field.
  315. //      "Never"     - never deref aliases.  return only the alias.
  316. //      "Searching" - only deref aliases when searching, not when locating
  317. //                    the base object of a search.
  318. //      "Finding"   - dereference the alias when locating the base object but
  319. //                    not during a search.
  320. //      "Always"    - always dereference aliases.
  321. //
  322.  
  323. #define LDAP_DEREF_NEVER        0
  324. #define LDAP_DEREF_SEARCHING    1
  325. #define LDAP_DEREF_FINDING      2
  326. #define LDAP_DEREF_ALWAYS       3
  327.  
  328. //  Special values for ld_sizelimit :
  329.  
  330. #define LDAP_NO_LIMIT       0
  331.  
  332. //  Flags for ld_options field :
  333.  
  334. #define LDAP_OPT_DNS                0x00000001  // utilize DN & DNS
  335. #define LDAP_OPT_CHASE_REFERRALS    0x00000002  // chase referrals
  336. #define LDAP_OPT_RETURN_REFS        0x00000004  // return referrals to calling app
  337.  
  338. //
  339. //  LDAP structure per connection
  340. //
  341.  
  342. #pragma pack(push, 4)
  343.  
  344. typedef struct ldap {
  345.  
  346.     struct {
  347.  
  348.         ULONG sb_sd;
  349.  
  350.         UCHAR Reserved1[(10*sizeof(ULONG))+1];
  351.  
  352.         ULONG sb_naddr;   // notzero implies CLDAP available
  353.  
  354.         UCHAR Reserved2[(6*sizeof(ULONG))];
  355.  
  356.     } ld_sb;
  357.  
  358.     //
  359.     //  Following parameters MAY match up to reference implementation of LDAP
  360.     //
  361.  
  362.     PCHAR   ld_host;
  363.     ULONG   ld_version;
  364.     UCHAR   ld_lberoptions;
  365.  
  366.     //
  367.     //  Safe to assume that these parameters are in same location as
  368.     //  reference implementation of LDAP API.
  369.     //
  370.  
  371.     ULONG   ld_deref;
  372.  
  373.     ULONG   ld_timelimit;
  374.     ULONG   ld_sizelimit;
  375.  
  376.     ULONG   ld_errno;
  377.     PCHAR   ld_matched;
  378.     PCHAR   ld_error;
  379.     ULONG   ld_msgid;
  380.  
  381.     UCHAR Reserved3[(6*sizeof(ULONG))+1];
  382.  
  383.     //
  384.     //  Following parameters may match up to reference implementation of LDAP API.
  385.     //
  386.  
  387.     ULONG   ld_cldaptries;
  388.     ULONG   ld_cldaptimeout;
  389.     ULONG   ld_refhoplimit;
  390.     ULONG   ld_options;
  391.  
  392. } LDAP, * PLDAP;
  393.  
  394. //
  395. //  Our timeval structure is a bit different from the reference implementation
  396. //  since Win32 defines a _timeval structure that is different from the LDAP
  397. //  one.
  398. //
  399.  
  400. typedef struct l_timeval {
  401.     LONG    tv_sec;
  402.     LONG    tv_usec;
  403. } LDAP_TIMEVAL, * PLDAP_TIMEVAL;
  404.  
  405. //
  406. //  The berval structure is used to pass in any arbitrary octet string.  It
  407. //  is useful for attributes that cannot be represented using a null
  408. //  terminated string.
  409. //
  410.  
  411. typedef struct berval {
  412.     ULONG  bv_len;
  413.     PCHAR  bv_val;
  414. } LDAP_BERVAL, * PLDAP_BERVAL;
  415.  
  416. //
  417. //  The following structure has to be compatible with reference implementation.
  418. //
  419.  
  420. typedef struct ldapmsg {
  421.  
  422.     ULONG lm_msgid;             // message number for given connection
  423.     ULONG lm_msgtype;           // message type of the form LDAP_RES_xxx
  424.  
  425.     PVOID lm_ber;               // ber form of message
  426.  
  427.     struct ldapmsg *lm_chain;   // pointer to next result value
  428.     struct ldapmsg *lm_next;    // pointer to next message
  429.     ULONG lm_time;
  430.  
  431.     //
  432.     //  new fields below not in reference implementation
  433.     //
  434.  
  435.     PLDAP   Connection;         // connection from which we received response
  436.     PVOID   Request;            // owning request (opaque structure)
  437.     ULONG   lm_returncode;      // server's return code
  438.     USHORT  lm_referral;        // index of referral within ref table
  439.     BOOLEAN lm_chased;          // has referral been chased already?
  440.     BOOLEAN lm_eom;             // is this the last entry for this message?
  441.  
  442. } LDAPMessage, *PLDAPMessage;
  443.  
  444. //
  445. //  Controls... there are three types :
  446. //
  447. //   1) those passed to the server
  448. //   2) those passed to the client and handled by the client API
  449. //   3) those returned by the server
  450. //
  451.  
  452. typedef struct ldapcontrolA {
  453.  
  454.     PCHAR         ldctl_oid;
  455.     struct berval ldctl_value;
  456.     BOOLEAN       ldctl_iscritical;
  457.  
  458. } LDAPControlA, *PLDAPControlA;
  459.  
  460. typedef struct ldapcontrolW {
  461.  
  462.     PWCHAR        ldctl_oid;
  463.     struct berval ldctl_value;
  464.     BOOLEAN       ldctl_iscritical;
  465.  
  466. } LDAPControlW, *PLDAPControlW;
  467.  
  468. #if LDAP_UNICODE
  469. #define LDAPControl LDAPControlW
  470. #define PLDAPControl PLDAPControlW
  471. #else
  472. #define LDAPControl LDAPControlA
  473. #define PLDAPControl PLDAPControlA
  474. #endif
  475.  
  476. //
  477. //  Client controls section : these are the client controls that wldap32.dll
  478. //  supports.
  479. //
  480. //  If you specify LDAP_CONTROL_REFERRALS in a control, the value field should
  481. //  point to a ULONG of the following flags :
  482. //
  483. //      LDAP_CHASE_SUBORDINATE_REFERRALS
  484. //      LDAP_CHASE_EXTERNAL_REFERRALS
  485. //
  486.  
  487. #define LDAP_CONTROL_REFERRALS_W L"1.2.840.113556.1.4.616"
  488. #define LDAP_CONTROL_REFERRALS    "1.2.840.113556.1.4.616"
  489.  
  490. //
  491. //  Values required for Modification command  These are options for the
  492. //  mod_op field of LDAPMod structure
  493. //
  494.  
  495. #define LDAP_MOD_ADD            0x00
  496. #define LDAP_MOD_DELETE         0x01
  497. #define LDAP_MOD_REPLACE        0x02
  498. #define LDAP_MOD_BVALUES        0x80  // AND in this flag if berval structure used
  499.  
  500. typedef struct ldapmodW {
  501.      ULONG     mod_op;
  502.      PWCHAR    mod_type;
  503.      union {
  504.         PWCHAR  *modv_strvals;
  505.         struct berval   **modv_bvals;
  506.     } mod_vals;
  507. } LDAPModW, *PLDAPModW;
  508.  
  509. typedef struct ldapmodA {
  510.      ULONG     mod_op;
  511.      PCHAR     mod_type;
  512.      union {
  513.         PCHAR  *modv_strvals;
  514.         struct berval   **modv_bvals;
  515.     } mod_vals;
  516. } LDAPModA, *PLDAPModA;
  517.  
  518. #if LDAP_UNICODE
  519. #define LDAPMod LDAPModW
  520. #define PLDAPMod PLDAPModW
  521. #else
  522. #define LDAPMod LDAPModA
  523. #define PLDAPMod PLDAPModA
  524. #endif
  525.  
  526. #pragma pack(pop)
  527.  
  528. //
  529. //  macros compatible with reference implementation...
  530. //
  531.  
  532. #define LDAP_IS_CLDAP( ld ) ( (ld)->ld_sb.sb_naddr > 0 )
  533. #define mod_values      mod_vals.modv_strvals
  534. #define mod_bvalues     mod_vals.modv_bvals
  535. #define NAME_ERROR(n)   ((n & 0xf0) == 0x20)
  536.  
  537. //
  538. //  function definitions for LDAP API
  539. //
  540.  
  541. //
  542. //  Create a connection block to an LDAP server.  HostName can be NULL, in
  543. //  which case we'll try to go off and find the "default" LDAP server.
  544. //
  545. //  Note that if we have to go off and find the default server, we'll pull
  546. //  in NETAPI32.DLL and ADVAPI32.DLL.
  547. //
  548. //  If it returns NULL, an error occurred.  Pick up error code with
  549. //     GetLastError().
  550. //
  551. //  ldap_open actually opens the connection at the time of the call,
  552. //  whereas ldap_init only opens the connection when an operation is performed
  553. //  that requires it.
  554. //
  555. //  multi-thread: ldap_open*, ldap_init*, and ldap_sslinit* calls are safe.
  556. //
  557.  
  558. WINLDAPAPI LDAP * LDAPAPI ldap_openW( PWCHAR HostName, ULONG PortNumber );
  559. WINLDAPAPI LDAP * LDAPAPI ldap_openA( PCHAR HostName, ULONG PortNumber );
  560.  
  561. WINLDAPAPI LDAP * LDAPAPI ldap_initW( PWCHAR HostName, ULONG PortNumber );
  562. WINLDAPAPI LDAP * LDAPAPI ldap_initA( PCHAR HostName, ULONG PortNumber );
  563.  
  564. WINLDAPAPI LDAP * LDAPAPI ldap_sslinitW( PWCHAR HostName, ULONG PortNumber, int secure );
  565. WINLDAPAPI LDAP * LDAPAPI ldap_sslinitA( PCHAR HostName, ULONG PortNumber, int secure );
  566.  
  567. //
  568. //  when calling ldap_init, you can call ldap_connect explicitly to have the
  569. //  library contact the server.  This is useful for checking for server
  570. //  availability.  This call is not required however, since the other functions
  571. //  will call it internally if it hasn't already been called.
  572. //
  573.  
  574. WINLDAPAPI ULONG LDAPAPI ldap_connect(  LDAP *ld,
  575.                                         struct l_timeval  *timeout
  576.                                         );
  577.  
  578. #if LDAP_UNICODE
  579.  
  580. #define ldap_open ldap_openW
  581. #define ldap_init ldap_initW
  582. #define ldap_sslinit ldap_sslinitW
  583.  
  584. #else
  585.  
  586. WINLDAPAPI LDAP * LDAPAPI ldap_open( PCHAR HostName, ULONG PortNumber );
  587. WINLDAPAPI LDAP * LDAPAPI ldap_init( PCHAR HostName, ULONG PortNumber );
  588. WINLDAPAPI LDAP * LDAPAPI ldap_sslinit( PCHAR HostName, ULONG PortNumber, int secure );
  589.  
  590. #endif
  591.  
  592. //
  593. //  This is similar to ldap_open except it creates a connection block for
  594. //  UDP based Connectionless LDAP services.  No TCP session is maintained.
  595. //
  596. //  If it returns NULL, an error occurred.  Pick up error code with
  597. //     GetLastError().
  598. //
  599. //  multi-thread: cldap_open* calls are safe.
  600. //
  601.  
  602. WINLDAPAPI LDAP * LDAPAPI cldap_openW( PWCHAR HostName, ULONG PortNumber );
  603. WINLDAPAPI LDAP * LDAPAPI cldap_openA( PCHAR HostName, ULONG PortNumber );
  604.  
  605.  
  606. #if LDAP_UNICODE
  607.  
  608. #define cldap_open cldap_openW
  609.  
  610. #else
  611.  
  612. WINLDAPAPI LDAP * LDAPAPI cldap_open( PCHAR HostName, ULONG PortNumber );
  613.  
  614. #endif
  615.  
  616.  
  617.  
  618. //
  619. //  Call unbind when you're done with the connection, it will free all
  620. //  resources associated with the connection.
  621. //
  622. //  There is no ldap_close... use ldap_unbind even if you haven't called
  623. //  ldap_bind on the connection.
  624. //
  625. //  multi-thread: ldap_unbind* calls are safe EXCEPT don't use the LDAP *
  626. //                stucture after it's been freed.
  627. //
  628.  
  629. WINLDAPAPI ULONG LDAPAPI ldap_unbind( LDAP *ld );
  630. WINLDAPAPI ULONG LDAPAPI ldap_unbind_s( LDAP *ld ); // calls ldap_unbind
  631.  
  632. //
  633. //  Calls to get and set options on connection blocks... use them rather
  634. //  than modifying the LDAP block directly.
  635. //
  636. //
  637. //  multi-thread: ldap_get_option is safe
  638. //  multi-thread: ldap_set_option is not safe in that it affects the
  639. //                connection as a whole.  beware if threads share connections.
  640.  
  641.  
  642. WINLDAPAPI ULONG LDAPAPI ldap_get_option( LDAP *ld, int option, void *outvalue );
  643. WINLDAPAPI ULONG LDAPAPI ldap_set_option( LDAP *ld, int option, void *invalue );
  644.  
  645. //
  646. //  These are the values to pass to ldap_get/set_option :
  647. //
  648.  
  649. #define LDAP_OPT_DESC               0x01
  650. #define LDAP_OPT_DEREF              0x02
  651. #define LDAP_OPT_SIZELIMIT          0x03
  652. #define LDAP_OPT_TIMELIMIT          0x04
  653. #define LDAP_OPT_THREAD_FN_PTRS     0x05
  654. #define LDAP_OPT_REBIND_FN          0x06
  655. #define LDAP_OPT_REBIND_ARG         0x07
  656. #define LDAP_OPT_REFERRALS          0x08
  657. #define LDAP_OPT_RESTART            0x09
  658.  
  659. #define LDAP_OPT_SSL                0x0a
  660. #define LDAP_OPT_IO_FN_PTRS         0x0b
  661. #define LDAP_OPT_CACHE_FN_PTRS      0x0d
  662. #define LDAP_OPT_CACHE_STRATEGY     0x0e
  663. #define LDAP_OPT_CACHE_ENABLE       0x0f
  664. #define LDAP_OPT_REFERRAL_HOP_LIMIT 0x10
  665.  
  666. #define LDAP_OPT_PROTOCOL_VERSION   0x11        // known by two names.
  667. #define LDAP_OPT_VERSION            0x11
  668.  
  669. //
  670. //  These are new ones that we've defined, not in current RFC draft.
  671. //
  672.  
  673. #define LDAP_OPT_HOST_NAME          0x30
  674. #define LDAP_OPT_ERROR_NUMBER       0x31
  675. #define LDAP_OPT_ERROR_STRING       0x32
  676. #define LDAP_OPT_HOST_REACHABLE     0x3E
  677.  
  678. //
  679. //  These options control the keep-alive logic.  Keep alives are sent as
  680. //  ICMP ping messages (which currently don't go through firewalls).
  681. //
  682. //  There are three values that control how this works :
  683. //  PING_KEEP_ALIVE : min number of seconds since we last received a response
  684. //                    from the server before we send a keep-alive ping
  685. //  PING_WAIT_TIME  : number of milliseconds we wait for the response to
  686. //                    come back when we send a ping
  687. //  PING_LIMIT      : number of unanswered pings we send before we close the
  688. //                    connection.
  689. //
  690. //  To disable the keep-alive logic, set any of the values (PING_KEEP_ALIVE,
  691. //  PING_LIMIT, or PING_WAIT_TIME) to zero.
  692. //
  693. //  The current default/min/max for these values are as follows :
  694. //
  695. //  PING_KEEP_ALIVE :  120/5/maxInt  seconds (may also be zero)
  696. //  PING_WAIT_TIME  :  2000/10/60000 milliseconds (may also be zero)
  697. //  PING_LIMIT      :  4/0/maxInt
  698. //
  699.  
  700. #define LDAP_OPT_PING_KEEP_ALIVE    0x36
  701. #define LDAP_OPT_PING_WAIT_TIME     0x37
  702. #define LDAP_OPT_PING_LIMIT         0x38
  703.  
  704. //
  705. //  These won't be in the RFC.  Only use these if you're going to be dependent
  706. //  on our implementation.
  707. //
  708.  
  709. #define LDAP_OPT_DNSDOMAIN_NAME     0x3B    // return DNS name of domain
  710. #define LDAP_OPT_GETDSNAME_FLAGS    0x3D    // flags for DsGetDcName
  711.  
  712. #define LDAP_OPT_PROMPT_CREDENTIALS 0x3F    // prompt for creds? currently
  713.                                             // only for DPA & NTLM if no creds
  714.                                             // are loaded
  715.  
  716. //
  717. //  End of Microsoft only options
  718. //
  719.  
  720. #define LDAP_OPT_ON                 ((void *) 1)
  721. #define LDAP_OPT_OFF                ((void *) 0)
  722.  
  723. //
  724. //  For chasing referrals, we extend this a bit for LDAP_OPT_REFERRALS.  If
  725. //  the value is not LDAP_OPT_ON or LDAP_OPT_OFF, we'll treat them as the
  726. //  following :
  727. //
  728. //  LDAP_CHASE_SUBORDINATE_REFERRALS  : chase subordinate referrals (or
  729. //                                      references) returned in a v3 search
  730. //  LDAP_CHASE_EXTERNAL_REFERRALS : chase external referrals. These are
  731. //                          returned possibly on any operation except bind.
  732. //
  733. //  If you OR these flags together, it's equivalent to setting referrals to
  734. //  LDAP_OPT_ON.
  735. //
  736.  
  737. #define LDAP_CHASE_SUBORDINATE_REFERRALS    0x00000020
  738. #define LDAP_CHASE_EXTERNAL_REFERRALS       0x00000040
  739.  
  740. //
  741. //  Bind is required as the first operation to v2 servers, not so for v3
  742. //  servers.  See above description of authentication methods.
  743. //
  744. //  multi-thread: bind calls are not safe in that it affects the
  745. //                connection as a whole.  beware if threads share connections
  746. //                and try to mulithread binds with other operations.
  747.  
  748.  
  749. WINLDAPAPI ULONG LDAPAPI ldap_simple_bindW( LDAP *ld, PWCHAR dn, PWCHAR passwd );
  750. WINLDAPAPI ULONG LDAPAPI ldap_simple_bindA( LDAP *ld, PCHAR dn, PCHAR passwd );
  751. WINLDAPAPI ULONG LDAPAPI ldap_simple_bind_sW( LDAP *ld, PWCHAR dn, PWCHAR passwd );
  752. WINLDAPAPI ULONG LDAPAPI ldap_simple_bind_sA( LDAP *ld, PCHAR dn, PCHAR passwd );
  753.  
  754. WINLDAPAPI ULONG LDAPAPI ldap_bindW( LDAP *ld, PWCHAR dn, PWCHAR cred, ULONG method );
  755. WINLDAPAPI ULONG LDAPAPI ldap_bindA( LDAP *ld, PCHAR dn, PCHAR cred, ULONG method );
  756. WINLDAPAPI ULONG LDAPAPI ldap_bind_sW( LDAP *ld, PWCHAR dn, PWCHAR cred, ULONG method );
  757. WINLDAPAPI ULONG LDAPAPI ldap_bind_sA( LDAP *ld, PCHAR dn, PCHAR cred, ULONG method );
  758.  
  759. #if 0
  760.  
  761.     //
  762.     //  Pending discussions with the IETF... we won't implement the extended
  763.     //  form of bind until we determine what the API will look like.
  764.     //
  765.  
  766. WINLDAPAPI ULONG LDAPAPI ldap_bind_extW(    LDAP *ld,
  767.                                             PWCHAR dn,
  768.                                             PWCHAR cred,
  769.                                             ULONG method,
  770.                                             PLDAPControlW *ServerControls,
  771.                                             PLDAPControlW *ClientControls,
  772.                                             ULONG   TimeLimit,
  773.                                             ULONG  *MessageNumber
  774.                                             );
  775. WINLDAPAPI ULONG LDAPAPI ldap_bind_extA(    LDAP *ld,
  776.                                             PCHAR dn,
  777.                                             PCHAR cred,
  778.                                             ULONG method,
  779.                                             PLDAPControlA *ServerControls,
  780.                                             PLDAPControlA *ClientControls,
  781.                                             ULONG   TimeLimit,
  782.                                             ULONG  *MessageNumber
  783.                                             );
  784. WINLDAPAPI ULONG LDAPAPI ldap_bind_ext_sW(  LDAP *ld,
  785.                                             PWCHAR dn,
  786.                                             PWCHAR cred,
  787.                                             ULONG method,
  788.                                             PLDAPControlW *ServerControls,
  789.                                             PLDAPControlW *ClientControls,
  790.                                             ULONG   TimeLimit
  791.                                             );
  792. WINLDAPAPI ULONG LDAPAPI ldap_bind_ext_sA(  LDAP *ld,
  793.                                             PCHAR dn,
  794.                                             PCHAR cred,
  795.                                             ULONG method,
  796.                                             PLDAPControlA *ServerControls,
  797.                                             PLDAPControlA *ClientControls,
  798.                                             ULONG   TimeLimit
  799.                                             );
  800. #endif
  801.  
  802.  
  803. #if LDAP_UNICODE
  804.  
  805. #define ldap_simple_bind ldap_simple_bindW
  806. #define ldap_simple_bind_s ldap_simple_bind_sW
  807.  
  808. #define ldap_bind ldap_bindW
  809. #define ldap_bind_s ldap_bind_sW
  810.  
  811. #if 0
  812.  
  813. #define ldap_bind_ext ldap_bind_extW
  814. #define ldap_bind_ext_s ldap_bind_ext_sW
  815.  
  816. #endif
  817.  
  818. #else
  819.  
  820. WINLDAPAPI ULONG LDAPAPI ldap_simple_bind( LDAP *ld, PCHAR dn, PCHAR passwd );
  821. WINLDAPAPI ULONG LDAPAPI ldap_simple_bind_s( LDAP *ld, PCHAR dn, PCHAR passwd );
  822.  
  823. WINLDAPAPI ULONG LDAPAPI ldap_bind( LDAP *ld, PCHAR dn, PCHAR cred, ULONG method );
  824. WINLDAPAPI ULONG LDAPAPI ldap_bind_s( LDAP *ld, PCHAR dn, PCHAR cred, ULONG method );
  825.  
  826. #if 0
  827.  
  828. WINLDAPAPI ULONG LDAPAPI ldap_bind_ext(     LDAP *ld,
  829.                                             PCHAR dn,
  830.                                             PCHAR cred,
  831.                                             ULONG method,
  832.                                             PLDAPControlA *ServerControls,
  833.                                             PLDAPControlA *ClientControls,
  834.                                             ULONG   TimeLimit,
  835.                                             ULONG  *MessageNumber
  836.                                             );
  837. WINLDAPAPI ULONG LDAPAPI ldap_bind_ext_s(   LDAP *ld,
  838.                                             PCHAR dn,
  839.                                             PCHAR cred,
  840.                                             ULONG method,
  841.                                             PLDAPControlA *ServerControls,
  842.                                             PLDAPControlA *ClientControls,
  843.                                             ULONG   TimeLimit
  844.                                             );
  845. #endif
  846.  
  847. #endif
  848.  
  849. //
  850. //  Synchronous and asynch search routines.
  851. //
  852. //  filter follows RFC 1960 with the addition that '(' ')' '*' ' ' '\' and
  853. //   '\0' are all escaped with '\'
  854. //
  855. // Scope of search.  This corresponds to the "scope" parameter on search
  856.  
  857. #define LDAP_SCOPE_BASE         0x00
  858. #define LDAP_SCOPE_ONELEVEL     0x01
  859. #define LDAP_SCOPE_SUBTREE      0x02
  860.  
  861. //
  862. //  multi-thread: ldap_search calls are not safe in that the message number
  863. //                is returned rather than the return code.  You have to look
  864. //                at the connection block in an error case and the return code
  865. //                may be overwritten by another thread inbetween.
  866. //
  867. //                Use ldap_search_ext instead, as these are thread safe.
  868. //
  869. //                ldap_search_s and ldap_search_ext* calls are thread safe.
  870. //
  871.  
  872. WINLDAPAPI ULONG LDAPAPI ldap_searchW(
  873.         LDAP    *ld,
  874.         PWCHAR  base,           // distinguished name or ""
  875.         ULONG   scope,          // LDAP_SCOPE_xxxx
  876.         PWCHAR  filter,
  877.         PWCHAR  attrs[],        // pointer to an array of PCHAR attribute names
  878.         ULONG   attrsonly       // boolean on whether to only return attr names
  879.     );
  880. WINLDAPAPI ULONG LDAPAPI ldap_searchA(
  881.         LDAP    *ld,
  882.         PCHAR   base,           // distinguished name or ""
  883.         ULONG   scope,          // LDAP_SCOPE_xxxx
  884.         PCHAR   filter,
  885.         PCHAR   attrs[],        // pointer to an array of PCHAR attribute names
  886.         ULONG   attrsonly       // boolean on whether to only return attr names
  887.     );
  888.  
  889. WINLDAPAPI ULONG LDAPAPI ldap_search_sW(
  890.         LDAP            *ld,
  891.         PWCHAR          base,
  892.         ULONG           scope,
  893.         PWCHAR          filter,
  894.         PWCHAR          attrs[],
  895.         ULONG           attrsonly,
  896.         LDAPMessage     **res
  897.     );
  898. WINLDAPAPI ULONG LDAPAPI ldap_search_sA(
  899.         LDAP            *ld,
  900.         PCHAR           base,
  901.         ULONG           scope,
  902.         PCHAR           filter,
  903.         PCHAR           attrs[],
  904.         ULONG           attrsonly,
  905.         LDAPMessage     **res
  906.     );
  907.  
  908. WINLDAPAPI ULONG LDAPAPI ldap_search_stW(
  909.         LDAP            *ld,
  910.         PWCHAR          base,
  911.         ULONG           scope,
  912.         PWCHAR          filter,
  913.         PWCHAR          attrs[],
  914.         ULONG           attrsonly,
  915.         struct l_timeval  *timeout,
  916.         LDAPMessage     **res
  917.     );
  918. WINLDAPAPI ULONG LDAPAPI ldap_search_stA(
  919.         LDAP            *ld,
  920.         PCHAR           base,
  921.         ULONG           scope,
  922.         PCHAR           filter,
  923.         PCHAR           attrs[],
  924.         ULONG           attrsonly,
  925.         struct l_timeval  *timeout,
  926.         LDAPMessage     **res
  927.     );
  928.  
  929.  
  930. WINLDAPAPI ULONG LDAPAPI ldap_search_extW(
  931.         LDAP            *ld,
  932.         PWCHAR          base,
  933.         ULONG           scope,
  934.         PWCHAR          filter,
  935.         PWCHAR          attrs[],
  936.         ULONG           attrsonly,
  937.         PLDAPControlW   *ServerControls,
  938.         PLDAPControlW   *ClientControls,
  939.         ULONG           TimeLimit,
  940.         ULONG           SizeLimit,
  941.         ULONG           *MessageNumber
  942.     );
  943.  
  944. WINLDAPAPI ULONG LDAPAPI ldap_search_extA(
  945.         LDAP            *ld,
  946.         PCHAR           base,
  947.         ULONG           scope,
  948.         PCHAR           filter,
  949.         PCHAR           attrs[],
  950.         ULONG           attrsonly,
  951.         PLDAPControlA   *ServerControls,
  952.         PLDAPControlA   *ClientControls,
  953.         ULONG           TimeLimit,
  954.         ULONG           SizeLimit,
  955.         ULONG           *MessageNumber
  956.     );
  957.  
  958. WINLDAPAPI ULONG LDAPAPI ldap_search_ext_sW(
  959.         LDAP            *ld,
  960.         PWCHAR          base,
  961.         ULONG           scope,
  962.         PWCHAR          filter,
  963.         PWCHAR          attrs[],
  964.         ULONG           attrsonly,
  965.         PLDAPControlW   *ServerControls,
  966.         PLDAPControlW   *ClientControls,
  967.         struct l_timeval  *timeout,
  968.         ULONG           SizeLimit,
  969.         LDAPMessage     **res
  970.     );
  971.  
  972. WINLDAPAPI ULONG LDAPAPI ldap_search_ext_sA(
  973.         LDAP            *ld,
  974.         PCHAR           base,
  975.         ULONG           scope,
  976.         PCHAR           filter,
  977.         PCHAR           attrs[],
  978.         ULONG           attrsonly,
  979.         PLDAPControlA   *ServerControls,
  980.         PLDAPControlA   *ClientControls,
  981.         struct l_timeval  *timeout,
  982.         ULONG           SizeLimit,
  983.         LDAPMessage     **res
  984.     );
  985.  
  986. #if LDAP_UNICODE
  987.  
  988. #define ldap_search ldap_searchW
  989. #define ldap_search_s ldap_search_sW
  990. #define ldap_search_st ldap_search_stW
  991.  
  992. #define ldap_search_ext ldap_search_extW
  993. #define ldap_search_ext_s ldap_search_ext_sW
  994.  
  995. #else
  996.  
  997. WINLDAPAPI ULONG LDAPAPI ldap_search(
  998.         LDAP    *ld,
  999.         PCHAR   base,           // distinguished name or ""
  1000.         ULONG   scope,          // LDAP_SCOPE_xxxx
  1001.         PCHAR   filter,
  1002.         PCHAR   attrs[],        // pointer to an array of PCHAR attribute names
  1003.         ULONG   attrsonly       // boolean on whether to only return attr names
  1004.     );
  1005.  
  1006. WINLDAPAPI ULONG LDAPAPI ldap_search_s(
  1007.         LDAP            *ld,
  1008.         PCHAR           base,
  1009.         ULONG           scope,
  1010.         PCHAR           filter,
  1011.         PCHAR           attrs[],
  1012.         ULONG           attrsonly,
  1013.         LDAPMessage     **res
  1014.     );
  1015.  
  1016. WINLDAPAPI ULONG LDAPAPI ldap_search_st(
  1017.         LDAP            *ld,
  1018.         PCHAR           base,
  1019.         ULONG           scope,
  1020.         PCHAR           filter,
  1021.         PCHAR           attrs[],
  1022.         ULONG           attrsonly,
  1023.         struct l_timeval  *timeout,
  1024.         LDAPMessage     **res
  1025.     );
  1026.  
  1027. WINLDAPAPI ULONG LDAPAPI ldap_search_ext(
  1028.         LDAP            *ld,
  1029.         PCHAR           base,
  1030.         ULONG           scope,
  1031.         PCHAR           filter,
  1032.         PCHAR           attrs[],
  1033.         ULONG           attrsonly,
  1034.         PLDAPControlA   *ServerControls,
  1035.         PLDAPControlA   *ClientControls,
  1036.         ULONG           TimeLimit,
  1037.         ULONG           SizeLimit,
  1038.         ULONG           *MessageNumber
  1039.     );
  1040.  
  1041. WINLDAPAPI ULONG LDAPAPI ldap_search_ext_s(
  1042.         LDAP            *ld,
  1043.         PCHAR           base,
  1044.         ULONG           scope,
  1045.         PCHAR           filter,
  1046.         PCHAR           attrs[],
  1047.         ULONG           attrsonly,
  1048.         PLDAPControlA   *ServerControls,
  1049.         PLDAPControlA   *ClientControls,
  1050.         struct l_timeval  *timeout,
  1051.         ULONG           SizeLimit,
  1052.         LDAPMessage     **res
  1053.     );
  1054.  
  1055. #endif
  1056.  
  1057.  
  1058.  
  1059. //
  1060. //  modify an existing entry
  1061. //
  1062.  
  1063. //
  1064. //  multi-thread: ldap_modify calls are not safe in that the message number
  1065. //                is returned rather than the return code.  You have to look
  1066. //                at the connection block in an error case and the return code
  1067. //                may be overwritten by another thread inbetween.
  1068. //
  1069. //                Use ldap_modify_ext instead, as these are thread safe.
  1070. //
  1071. //                ldap_modify_s and ldap_modify_ext* calls are thread safe.
  1072. //
  1073.  
  1074. WINLDAPAPI ULONG LDAPAPI ldap_modifyW( LDAP *ld, PWCHAR dn, LDAPModW *mods[] );
  1075. WINLDAPAPI ULONG LDAPAPI ldap_modifyA( LDAP *ld, PCHAR dn, LDAPModA *mods[] );
  1076.  
  1077. WINLDAPAPI ULONG LDAPAPI ldap_modify_sW( LDAP *ld, PWCHAR dn, LDAPModW *mods[] );
  1078. WINLDAPAPI ULONG LDAPAPI ldap_modify_sA( LDAP *ld, PCHAR dn, LDAPModA *mods[] );
  1079.  
  1080. WINLDAPAPI ULONG LDAPAPI ldap_modify_extW(
  1081.         LDAP *ld,
  1082.         PWCHAR dn,
  1083.         LDAPModW *mods[],
  1084.         PLDAPControlW   *ServerControls,
  1085.         PLDAPControlW   *ClientControls,
  1086.         ULONG           *MessageNumber
  1087.         );
  1088.  
  1089. WINLDAPAPI ULONG LDAPAPI ldap_modify_extA(
  1090.         LDAP *ld,
  1091.         PCHAR dn,
  1092.         LDAPModA *mods[],
  1093.         PLDAPControlA   *ServerControls,
  1094.         PLDAPControlA   *ClientControls,
  1095.         ULONG           *MessageNumber
  1096.         );
  1097.  
  1098. WINLDAPAPI ULONG LDAPAPI ldap_modify_ext_sW(
  1099.         LDAP *ld,
  1100.         PWCHAR dn,
  1101.         LDAPModW *mods[],
  1102.         PLDAPControlW   *ServerControls,
  1103.         PLDAPControlW   *ClientControls
  1104.         );
  1105.  
  1106. WINLDAPAPI ULONG LDAPAPI ldap_modify_ext_sA(
  1107.         LDAP *ld,
  1108.         PCHAR dn,
  1109.         LDAPModA *mods[],
  1110.         PLDAPControlA   *ServerControls,
  1111.         PLDAPControlA   *ClientControls
  1112.         );
  1113.  
  1114. #if LDAP_UNICODE
  1115.  
  1116. #define ldap_modify ldap_modifyW
  1117. #define ldap_modify_s ldap_modify_sW
  1118.  
  1119. #define ldap_modify_ext ldap_modify_extW
  1120. #define ldap_modify_ext_s ldap_modify_ext_sW
  1121.  
  1122. #else
  1123.  
  1124. WINLDAPAPI ULONG LDAPAPI ldap_modify( LDAP *ld, PCHAR dn, LDAPModA *mods[] );
  1125. WINLDAPAPI ULONG LDAPAPI ldap_modify_s( LDAP *ld, PCHAR dn, LDAPModA *mods[] );
  1126.  
  1127. WINLDAPAPI ULONG LDAPAPI ldap_modify_ext(
  1128.         LDAP *ld,
  1129.         PCHAR dn,
  1130.         LDAPModA *mods[],
  1131.         PLDAPControlA   *ServerControls,
  1132.         PLDAPControlA   *ClientControls,
  1133.         ULONG           *MessageNumber
  1134.         );
  1135.  
  1136. WINLDAPAPI ULONG LDAPAPI ldap_modify_ext_s(
  1137.         LDAP *ld,
  1138.         PCHAR dn,
  1139.         LDAPModA *mods[],
  1140.         PLDAPControlA   *ServerControls,
  1141.         PLDAPControlA   *ClientControls
  1142.         );
  1143. #endif
  1144.  
  1145. //
  1146. //  modrdn and modrdn2 function both as RenameObject and MoveObject.
  1147. //
  1148. //  Note that to LDAP v2 servers, only rename within a given container
  1149. //  is supported... therefore NewDistinguishedName is actually NewRDN.
  1150. //  Here are some examples :
  1151. //
  1152. //  This works to both v2 and v3 servers :
  1153. //
  1154. //    DN = CN=Bob,OU=FOO,O=BAR
  1155. //    NewDN = CN=Joe
  1156. //
  1157. //    result is: CN=Joe,OU=FOO,O=BAR
  1158. //
  1159. //  This works to only v3 and above servers :
  1160. //
  1161. //    DN = CN=Bob,OU=FOO,O=BAR
  1162. //    NewDN = CN=Joe,OU=FOOBAR,O=BAR
  1163. //
  1164. //    result is: CN=Joe,OU=FOOBAR,O=BAR
  1165. //
  1166. //  If you try the second example to a v2 server, we'll send the whole
  1167. //  NewDN over as the new RDN (rather than break up the parent OU and
  1168. //  child).  The server will then give you back some unknown error.
  1169. //
  1170.  
  1171. //
  1172. //  multi-thread: ldap_modrdn and ldap_modrdn2 calls are not safe in that
  1173. //                the message number is returned rather than the return code.
  1174. //                You have to look   at the connection block in an error case
  1175. //                and the return code may be overwritten by another thread
  1176. //                inbetween.
  1177. //
  1178. //                Use ldap_rename_ext instead, as these are thread safe.
  1179. //
  1180.  
  1181. WINLDAPAPI ULONG LDAPAPI ldap_modrdn2W (
  1182.     LDAP    *ExternalHandle,
  1183.     PWCHAR  DistinguishedName,
  1184.     PWCHAR  NewDistinguishedName,
  1185.     INT     DeleteOldRdn
  1186.     );
  1187. WINLDAPAPI ULONG LDAPAPI ldap_modrdn2A (
  1188.     LDAP    *ExternalHandle,
  1189.     PCHAR   DistinguishedName,
  1190.     PCHAR   NewDistinguishedName,
  1191.     INT     DeleteOldRdn
  1192.     );
  1193.  
  1194. //
  1195. //  ldap_modrdn simply calls ldap_modrdn2 with a value of 1 for DeleteOldRdn.
  1196. //
  1197.  
  1198. WINLDAPAPI ULONG LDAPAPI ldap_modrdnW (
  1199.     LDAP    *ExternalHandle,
  1200.     PWCHAR   DistinguishedName,
  1201.     PWCHAR   NewDistinguishedName
  1202.     );
  1203. WINLDAPAPI ULONG LDAPAPI ldap_modrdnA (
  1204.     LDAP    *ExternalHandle,
  1205.     PCHAR   DistinguishedName,
  1206.     PCHAR   NewDistinguishedName
  1207.     );
  1208.  
  1209. WINLDAPAPI ULONG LDAPAPI ldap_modrdn2_sW (
  1210.     LDAP    *ExternalHandle,
  1211.     PWCHAR   DistinguishedName,
  1212.     PWCHAR   NewDistinguishedName,
  1213.     INT     DeleteOldRdn
  1214.     );
  1215. WINLDAPAPI ULONG LDAPAPI ldap_modrdn2_sA (
  1216.     LDAP    *ExternalHandle,
  1217.     PCHAR   DistinguishedName,
  1218.     PCHAR   NewDistinguishedName,
  1219.     INT     DeleteOldRdn
  1220.     );
  1221.  
  1222. WINLDAPAPI ULONG LDAPAPI ldap_modrdn_sW (
  1223.     LDAP    *ExternalHandle,
  1224.     PWCHAR   DistinguishedName,
  1225.     PWCHAR   NewDistinguishedName
  1226.     );
  1227. WINLDAPAPI ULONG LDAPAPI ldap_modrdn_sA (
  1228.     LDAP    *ExternalHandle,
  1229.     PCHAR   DistinguishedName,
  1230.     PCHAR   NewDistinguishedName
  1231.     );
  1232.  
  1233. #if LDAP_UNICODE
  1234.  
  1235. #define ldap_modrdn2 ldap_modrdn2W
  1236. #define ldap_modrdn ldap_modrdnW
  1237. #define ldap_modrdn2_s ldap_modrdn2_sW
  1238. #define ldap_modrdn_s ldap_modrdn_sW
  1239.  
  1240. #else
  1241.  
  1242. WINLDAPAPI ULONG LDAPAPI ldap_modrdn2 (
  1243.     LDAP    *ExternalHandle,
  1244.     PCHAR   DistinguishedName,
  1245.     PCHAR   NewDistinguishedName,
  1246.     INT     DeleteOldRdn
  1247.     );
  1248. WINLDAPAPI ULONG LDAPAPI ldap_modrdn (
  1249.     LDAP    *ExternalHandle,
  1250.     PCHAR   DistinguishedName,
  1251.     PCHAR   NewDistinguishedName
  1252.     );
  1253. WINLDAPAPI ULONG LDAPAPI ldap_modrdn2_s (
  1254.     LDAP    *ExternalHandle,
  1255.     PCHAR   DistinguishedName,
  1256.     PCHAR   NewDistinguishedName,
  1257.     INT     DeleteOldRdn
  1258.     );
  1259. WINLDAPAPI ULONG LDAPAPI ldap_modrdn_s (
  1260.     LDAP    *ExternalHandle,
  1261.     PCHAR   DistinguishedName,
  1262.     PCHAR   NewDistinguishedName
  1263.     );
  1264.  
  1265. #endif
  1266.  
  1267. //
  1268. //  Extended Rename operations.  These take controls and separate out the
  1269. //  parent from the RDN, for clarity.
  1270. //
  1271.  
  1272. WINLDAPAPI ULONG LDAPAPI ldap_rename_extW(
  1273.         LDAP *ld,
  1274.         PWCHAR dn,
  1275.         PWCHAR NewRDN,
  1276.         PWCHAR NewParent,
  1277.         INT DeleteOldRdn,
  1278.         PLDAPControlW   *ServerControls,
  1279.         PLDAPControlW   *ClientControls,
  1280.         ULONG           *MessageNumber
  1281.         );
  1282.  
  1283. WINLDAPAPI ULONG LDAPAPI ldap_rename_extA(
  1284.         LDAP *ld,
  1285.         PCHAR dn,
  1286.         PCHAR NewRDN,
  1287.         PCHAR NewParent,
  1288.         INT DeleteOldRdn,
  1289.         PLDAPControlA   *ServerControls,
  1290.         PLDAPControlA   *ClientControls,
  1291.         ULONG           *MessageNumber
  1292.         );
  1293.  
  1294. WINLDAPAPI ULONG LDAPAPI ldap_rename_ext_sW(
  1295.         LDAP *ld,
  1296.         PWCHAR dn,
  1297.         PWCHAR NewRDN,
  1298.         PWCHAR NewParent,
  1299.         INT DeleteOldRdn,
  1300.         PLDAPControlW   *ServerControls,
  1301.         PLDAPControlW   *ClientControls
  1302.         );
  1303.  
  1304. WINLDAPAPI ULONG LDAPAPI ldap_rename_ext_sA(
  1305.         LDAP *ld,
  1306.         PCHAR dn,
  1307.         PCHAR NewRDN,
  1308.         PCHAR NewParent,
  1309.         INT DeleteOldRdn,
  1310.         PLDAPControlA   *ServerControls,
  1311.         PLDAPControlA   *ClientControls
  1312.         );
  1313.  
  1314. #if LDAP_UNICODE
  1315.  
  1316. #define ldap_rename_ext ldap_rename_extW
  1317. #define ldap_rename_ext_s ldap_rename_ext_sW
  1318.  
  1319. #else
  1320.  
  1321. WINLDAPAPI ULONG LDAPAPI ldap_rename_ext(
  1322.         LDAP *ld,
  1323.         PCHAR dn,
  1324.         PCHAR NewRDN,
  1325.         PCHAR NewParent,
  1326.         INT DeleteOldRdn,
  1327.         PLDAPControlA   *ServerControls,
  1328.         PLDAPControlA   *ClientControls,
  1329.         ULONG           *MessageNumber
  1330.         );
  1331.  
  1332. WINLDAPAPI ULONG LDAPAPI ldap_rename_ext_s(
  1333.         LDAP *ld,
  1334.         PCHAR dn,
  1335.         PCHAR NewRDN,
  1336.         PCHAR NewParent,
  1337.         INT DeleteOldRdn,
  1338.         PLDAPControlA   *ServerControls,
  1339.         PLDAPControlA   *ClientControls
  1340.         );
  1341. #endif
  1342.  
  1343. //
  1344. //  Add an entry to the tree
  1345. //
  1346.  
  1347. //
  1348. //  multi-thread: ldap_add calls are not safe in that the message number
  1349. //                is returned rather than the return code.  You have to look
  1350. //                at the connection block in an error case and the return code
  1351. //                may be overwritten by another thread inbetween.
  1352. //
  1353. //                Use ldap_add_ext instead, as these are thread safe.
  1354. //
  1355. //                ldap_add_s and ldap_add_ext* calls are thread safe.
  1356. //
  1357.  
  1358. WINLDAPAPI ULONG LDAPAPI ldap_addW( LDAP *ld, PWCHAR dn, LDAPModW *attrs[] );
  1359. WINLDAPAPI ULONG LDAPAPI ldap_addA( LDAP *ld, PCHAR dn, LDAPModA *attrs[] );
  1360.  
  1361. WINLDAPAPI ULONG LDAPAPI ldap_add_sW( LDAP *ld, PWCHAR dn, LDAPModW *attrs[] );
  1362. WINLDAPAPI ULONG LDAPAPI ldap_add_sA( LDAP *ld, PCHAR dn, LDAPModA *attrs[] );
  1363.  
  1364. WINLDAPAPI ULONG LDAPAPI ldap_add_extW(
  1365.         LDAP *ld,
  1366.         PWCHAR dn,
  1367.         LDAPModW *attrs[],
  1368.         PLDAPControlW   *ServerControls,
  1369.         PLDAPControlW   *ClientControls,
  1370.         ULONG           *MessageNumber
  1371.         );
  1372.  
  1373. WINLDAPAPI ULONG LDAPAPI ldap_add_extA(
  1374.         LDAP *ld,
  1375.         PCHAR dn,
  1376.         LDAPModA *attrs[],
  1377.         PLDAPControlA   *ServerControls,
  1378.         PLDAPControlA   *ClientControls,
  1379.         ULONG           *MessageNumber
  1380.         );
  1381.  
  1382. WINLDAPAPI ULONG LDAPAPI ldap_add_ext_sW(
  1383.         LDAP *ld,
  1384.         PWCHAR dn,
  1385.         LDAPModW *attrs[],
  1386.         PLDAPControlW   *ServerControls,
  1387.         PLDAPControlW   *ClientControls
  1388.         );
  1389.  
  1390. WINLDAPAPI ULONG LDAPAPI ldap_add_ext_sA(
  1391.         LDAP *ld,
  1392.         PCHAR dn,
  1393.         LDAPModA *attrs[],
  1394.         PLDAPControlA   *ServerControls,
  1395.         PLDAPControlA   *ClientControls
  1396.         );
  1397.  
  1398. #if LDAP_UNICODE
  1399.  
  1400. #define ldap_add ldap_addW
  1401. #define ldap_add_s ldap_add_sW
  1402.  
  1403. #define ldap_add_ext ldap_add_extW
  1404. #define ldap_add_ext_s ldap_add_ext_sW
  1405.  
  1406. #else
  1407.  
  1408. WINLDAPAPI ULONG LDAPAPI ldap_add( LDAP *ld, PCHAR dn, LDAPMod *attrs[] );
  1409. WINLDAPAPI ULONG LDAPAPI ldap_add_s( LDAP *ld, PCHAR dn, LDAPMod *attrs[] );
  1410.  
  1411. WINLDAPAPI ULONG LDAPAPI ldap_add_ext(
  1412.         LDAP *ld,
  1413.         PCHAR dn,
  1414.         LDAPModA *attrs[],
  1415.         PLDAPControlA   *ServerControls,
  1416.         PLDAPControlA   *ClientControls,
  1417.         ULONG           *MessageNumber
  1418.         );
  1419.  
  1420. WINLDAPAPI ULONG LDAPAPI ldap_add_ext_s(
  1421.         LDAP *ld,
  1422.         PCHAR dn,
  1423.         LDAPModA *attrs[],
  1424.         PLDAPControlA   *ServerControls,
  1425.         PLDAPControlA   *ClientControls
  1426.         );
  1427.  
  1428. #endif
  1429.  
  1430.  
  1431. //
  1432. //  Compare the attribute for a given entry to a known value.
  1433. //
  1434.  
  1435. //
  1436. //  multi-thread: ldap_compare calls are not safe in that the message number
  1437. //                is returned rather than the return code.  You have to look
  1438. //                at the connection block in an error case and the return code
  1439. //                may be overwritten by another thread inbetween.
  1440. //
  1441. //                Use ldap_compare_ext instead, as these are thread safe.
  1442. //
  1443. //                ldap_compare_s and ldap_compare_ext* calls are thread safe.
  1444. //
  1445.  
  1446.  
  1447. WINLDAPAPI ULONG LDAPAPI ldap_compareW( LDAP *ld, PWCHAR dn, PWCHAR attr, PWCHAR value );
  1448. WINLDAPAPI ULONG LDAPAPI ldap_compareA( LDAP *ld, PCHAR dn, PCHAR attr, PCHAR value );
  1449.  
  1450. WINLDAPAPI ULONG LDAPAPI ldap_compare_sW( LDAP *ld, PWCHAR dn, PWCHAR attr, PWCHAR value );
  1451. WINLDAPAPI ULONG LDAPAPI ldap_compare_sA( LDAP *ld, PCHAR dn, PCHAR attr, PCHAR value );
  1452.  
  1453. #if LDAP_UNICODE
  1454.  
  1455. #define ldap_compare ldap_compareW
  1456. #define ldap_compare_s ldap_compare_sW
  1457.  
  1458. #else
  1459.  
  1460. WINLDAPAPI ULONG LDAPAPI ldap_compare( LDAP *ld, PCHAR dn, PCHAR attr, PCHAR value );
  1461. WINLDAPAPI ULONG LDAPAPI ldap_compare_s( LDAP *ld, PCHAR dn, PCHAR attr, PCHAR value );
  1462.  
  1463. #endif
  1464.  
  1465. //
  1466. //  Extended Compare operations.  These take controls and are thread safe.
  1467. //  They also allow you to specify a bval structure for the data, so that it
  1468. //  isn't translated from Unicode or ANSI to UTF8.  Allows for comparison of
  1469. //  raw binary data.
  1470. //
  1471. //  Specify either Data or Value as not NULL.  If both are not NULL, the
  1472. //  berval Data will be used.
  1473. //
  1474.  
  1475. WINLDAPAPI ULONG LDAPAPI ldap_compare_extW(
  1476.         LDAP *ld,
  1477.         PWCHAR dn,
  1478.         PWCHAR Attr,
  1479.         PWCHAR Value,           // either value or Data is not null, not both
  1480.         struct berval   *Data,
  1481.         PLDAPControlW   *ServerControls,
  1482.         PLDAPControlW   *ClientControls,
  1483.         ULONG           *MessageNumber
  1484.         );
  1485.  
  1486. WINLDAPAPI ULONG LDAPAPI ldap_compare_extA(
  1487.         LDAP *ld,
  1488.         PCHAR dn,
  1489.         PCHAR Attr,
  1490.         PCHAR Value,            // either value or Data is not null, not both
  1491.         struct berval   *Data,
  1492.         PLDAPControlA   *ServerControls,
  1493.         PLDAPControlA   *ClientControls,
  1494.         ULONG           *MessageNumber
  1495.         );
  1496.  
  1497. WINLDAPAPI ULONG LDAPAPI ldap_compare_ext_sW(
  1498.         LDAP *ld,
  1499.         PWCHAR dn,
  1500.         PWCHAR Attr,
  1501.         PWCHAR Value,           // either value or Data is not null, not both
  1502.         struct berval   *Data,
  1503.         PLDAPControlW   *ServerControls,
  1504.         PLDAPControlW   *ClientControls
  1505.         );
  1506.  
  1507. WINLDAPAPI ULONG LDAPAPI ldap_compare_ext_sA(
  1508.         LDAP *ld,
  1509.         PCHAR dn,
  1510.         PCHAR Attr,
  1511.         PCHAR Value,            // either value or Data is not null, not both
  1512.         struct berval   *Data,
  1513.         PLDAPControlA   *ServerControls,
  1514.         PLDAPControlA   *ClientControls
  1515.         );
  1516.  
  1517. #if LDAP_UNICODE
  1518.  
  1519. #define ldap_compare_ext ldap_compare_extW
  1520. #define ldap_compare_ext_s ldap_compare_ext_sW
  1521.  
  1522. #else
  1523.  
  1524. WINLDAPAPI ULONG LDAPAPI ldap_compare_ext(
  1525.         LDAP *ld,
  1526.         PCHAR dn,
  1527.         PCHAR Attr,
  1528.         PCHAR Value,            // either value or Data is not null, not both
  1529.         struct berval   *Data,
  1530.         PLDAPControlA   *ServerControls,
  1531.         PLDAPControlA   *ClientControls,
  1532.         ULONG           *MessageNumber
  1533.         );
  1534.  
  1535. WINLDAPAPI ULONG LDAPAPI ldap_compare_ext_s(
  1536.         LDAP *ld,
  1537.         PCHAR dn,
  1538.         PCHAR Attr,
  1539.         PCHAR Value,            // either value or Data is not null, not both
  1540.         struct berval   *Data,
  1541.         PLDAPControlA   *ServerControls,
  1542.         PLDAPControlA   *ClientControls
  1543.         );
  1544. #endif
  1545.  
  1546.  
  1547. //
  1548. //  Delete an object out of the tree
  1549. //
  1550.  
  1551. //
  1552. //  multi-thread: ldap_delete calls are not safe in that the message number
  1553. //                is returned rather than the return code.  You have to look
  1554. //                at the connection block in an error case and the return code
  1555. //                may be overwritten by another thread inbetween.
  1556. //
  1557. //                Use ldap_delete_ext instead, as these are thread safe.
  1558. //
  1559. //                ldap_delete_s and ldap_delete_ext* calls are thread safe.
  1560. //
  1561.  
  1562.  
  1563. WINLDAPAPI ULONG LDAPAPI ldap_deleteW( LDAP *ld, PWCHAR dn );
  1564. WINLDAPAPI ULONG LDAPAPI ldap_deleteA( LDAP *ld, PCHAR dn );
  1565.  
  1566. WINLDAPAPI ULONG LDAPAPI ldap_delete_sW( LDAP *ld, PWCHAR dn );
  1567. WINLDAPAPI ULONG LDAPAPI ldap_delete_sA( LDAP *ld, PCHAR dn );
  1568.  
  1569. WINLDAPAPI ULONG LDAPAPI ldap_delete_extW(
  1570.         LDAP *ld,
  1571.         PWCHAR dn,
  1572.         PLDAPControlW   *ServerControls,
  1573.         PLDAPControlW   *ClientControls,
  1574.         ULONG           *MessageNumber
  1575.         );
  1576.  
  1577. WINLDAPAPI ULONG LDAPAPI ldap_delete_extA(
  1578.         LDAP *ld,
  1579.         PCHAR dn,
  1580.         PLDAPControlA   *ServerControls,
  1581.         PLDAPControlA   *ClientControls,
  1582.         ULONG           *MessageNumber
  1583.         );
  1584.  
  1585. WINLDAPAPI ULONG LDAPAPI ldap_delete_ext_sW(
  1586.         LDAP *ld,
  1587.         PWCHAR dn,
  1588.         PLDAPControlW   *ServerControls,
  1589.         PLDAPControlW   *ClientControls
  1590.         );
  1591.  
  1592. WINLDAPAPI ULONG LDAPAPI ldap_delete_ext_sA(
  1593.         LDAP *ld,
  1594.         PCHAR dn,
  1595.         PLDAPControlA   *ServerControls,
  1596.         PLDAPControlA   *ClientControls
  1597.         );
  1598.  
  1599. #if LDAP_UNICODE
  1600.  
  1601. #define ldap_delete ldap_deleteW
  1602. #define ldap_delete_ext ldap_delete_extW
  1603. #define ldap_delete_s ldap_delete_sW
  1604. #define ldap_delete_ext_s ldap_delete_ext_sW
  1605.  
  1606. #else
  1607.  
  1608. WINLDAPAPI ULONG LDAPAPI ldap_delete( LDAP *ld, PCHAR dn );
  1609. WINLDAPAPI ULONG LDAPAPI ldap_delete_s( LDAP *ld, PCHAR dn );
  1610.  
  1611. WINLDAPAPI ULONG LDAPAPI ldap_delete_ext(
  1612.         LDAP *ld,
  1613.         PCHAR dn,
  1614.         PLDAPControlA   *ServerControls,
  1615.         PLDAPControlA   *ClientControls,
  1616.         ULONG           *MessageNumber
  1617.         );
  1618.  
  1619. WINLDAPAPI ULONG LDAPAPI ldap_delete_ext_s(
  1620.         LDAP *ld,
  1621.         PCHAR dn,
  1622.         PLDAPControlA   *ServerControls,
  1623.         PLDAPControlA   *ClientControls
  1624.         );
  1625. #endif
  1626.  
  1627.  
  1628.  
  1629. //
  1630. //  Give up on a request.  No guarentee that it got there as there is no
  1631. //  response from the server.
  1632. //
  1633.  
  1634. //  multi-thread: ldap_abandon calls are thread safe
  1635.  
  1636. WINLDAPAPI ULONG LDAPAPI ldap_abandon( LDAP *ld, ULONG msgid );
  1637.  
  1638.  
  1639.  
  1640. //
  1641. //  Possible values for "all" field in ldap_result.  We've enhanced it such
  1642. //  that if someone passes in LDAP_MSG_RECEIVED, we'll pass all values we've
  1643. //  received up to that point.
  1644. //
  1645.  
  1646. #define LDAP_MSG_ONE    0
  1647. #define LDAP_MSG_ALL    1
  1648. #define LDAP_MSG_RECEIVED  2
  1649.  
  1650. //
  1651. //  Get a response from a connection.  One enhancement here is that ld can
  1652. //  be null, in which case we'll return responses from any server.  Free
  1653. //  responses here with ldap_msgfree.
  1654. //
  1655. //  For connection-less LDAP, you should pass in both a LDAP connection
  1656. //  handle and a msgid.  This will ensure we know which request the app
  1657. //  is waiting on a reply to.  ( we actively resend request until we get
  1658. //  a response.)
  1659. //
  1660.  
  1661. //  multi-thread: ldap_result calls are thread safe
  1662.  
  1663. WINLDAPAPI ULONG LDAPAPI ldap_result(
  1664.         LDAP            *ld,
  1665.         ULONG           msgid,
  1666.         ULONG           all,
  1667.         struct l_timeval  *timeout,
  1668.         LDAPMessage     **res
  1669.     );
  1670.  
  1671. WINLDAPAPI ULONG LDAPAPI ldap_msgfree( LDAPMessage *res );
  1672.  
  1673. //
  1674. //  This parses a message and returns the error code.  It optionally frees
  1675. //  the message by calling ldap_msgfree.
  1676. //
  1677.  
  1678. //  multi-thread: ldap_result2error call is thread safe
  1679.  
  1680. WINLDAPAPI ULONG LDAPAPI ldap_result2error(
  1681.         LDAP            *ld,
  1682.         LDAPMessage     *res,
  1683.         ULONG           freeit      // boolean.. free the message?
  1684.     );
  1685.  
  1686.  
  1687. //
  1688. //  Similar to ldap_result2error, this parses responses from the server and
  1689. //  returns the appropriate fields.  Use this one if you want to get at the
  1690. //  referrals, matchingDNs, or server controls returned.
  1691. //
  1692.  
  1693. //  multi-thread: ldap_parse_result call is thread safe
  1694.  
  1695. WINLDAPAPI ULONG LDAPAPI ldap_parse_resultW (
  1696.         LDAP *Connection,
  1697.         LDAPMessage *ResultMessage,
  1698.         ULONG *ReturnCode OPTIONAL,          // returned by server
  1699.         PWCHAR *MatchedDNs OPTIONAL,         // free with ldap_memfree
  1700.         PWCHAR *ErrorMessage OPTIONAL,       // free with ldap_memfree
  1701.         PWCHAR **Referrals OPTIONAL,         // free with ldap_value_freeW
  1702.         PLDAPControlW **ServerControls OPTIONAL,    // free with ldap_free_controlsW
  1703.         BOOLEAN Freeit
  1704.         );
  1705.  
  1706. WINLDAPAPI ULONG LDAPAPI ldap_parse_resultA (
  1707.         LDAP *Connection,
  1708.         LDAPMessage *ResultMessage,
  1709.         ULONG *ReturnCode OPTIONAL,         // returned by server
  1710.         PCHAR *MatchedDNs OPTIONAL,         // free with ldap_memfree
  1711.         PCHAR *ErrorMessage OPTIONAL,       // free with ldap_memfree
  1712.         PCHAR **Referrals OPTIONAL,         // free with ldap_value_freeA
  1713.         PLDAPControlA **ServerControls OPTIONAL,    // free with ldap_free_controlsA
  1714.         BOOLEAN Freeit
  1715.         );
  1716.  
  1717. WINLDAPAPI ULONG LDAPAPI ldap_controls_freeA (
  1718.         LDAPControlA **Controls
  1719.         );
  1720.  
  1721. WINLDAPAPI ULONG LDAPAPI ldap_control_freeA (
  1722.         LDAPControlA *Controls
  1723.         );
  1724.  
  1725. WINLDAPAPI ULONG LDAPAPI ldap_controls_freeW (
  1726.         LDAPControlW **Control
  1727.         );
  1728.  
  1729. WINLDAPAPI ULONG LDAPAPI ldap_control_freeW (
  1730.         LDAPControlW *Control
  1731.         );
  1732.  
  1733. //
  1734. // ldap_free_controls are old, use ldap_controls_free
  1735. //
  1736.  
  1737. WINLDAPAPI ULONG LDAPAPI ldap_free_controlsW (
  1738.         LDAPControlW **Controls
  1739.         );
  1740.  
  1741. WINLDAPAPI ULONG LDAPAPI ldap_free_controlsA (
  1742.         LDAPControlA **Controls
  1743.         );
  1744.  
  1745. #if LDAP_UNICODE
  1746.  
  1747. #define ldap_parse_result ldap_parse_resultW
  1748. #define ldap_controls_free ldap_controls_freeW
  1749. #define ldap_control_free ldap_control_freeW
  1750. #define ldap_free_controls ldap_free_controlsW
  1751.  
  1752. #else
  1753.  
  1754. WINLDAPAPI ULONG LDAPAPI ldap_parse_result (
  1755.         LDAP *Connection,
  1756.         LDAPMessage *ResultMessage,
  1757.         ULONG *ReturnCode OPTIONAL,         // returned by server
  1758.         PCHAR *MatchedDNs OPTIONAL,         // free with ldap_memfree
  1759.         PCHAR *ErrorMessage OPTIONAL,       // free with ldap_memfree
  1760.         PCHAR **Referrals OPTIONAL,         // free with ldap_value_free
  1761.         PLDAPControlA **ServerControls OPTIONAL,    // free with ldap_free_controls
  1762.         BOOLEAN Freeit
  1763.         );
  1764.  
  1765. WINLDAPAPI ULONG LDAPAPI ldap_controls_free (
  1766.         LDAPControlA **Controls
  1767.         );
  1768.  
  1769. WINLDAPAPI ULONG LDAPAPI ldap_control_free (
  1770.         LDAPControlA *Control
  1771.         );
  1772.  
  1773. WINLDAPAPI ULONG LDAPAPI ldap_free_controls (
  1774.         LDAPControlA **Controls
  1775.         );
  1776.  
  1777. #endif
  1778.  
  1779. //
  1780. //  ldap_err2string returns a pointer to a string describing the error.  This
  1781. //  string should not be freed.
  1782. //
  1783.  
  1784. WINLDAPAPI PWCHAR LDAPAPI ldap_err2stringW( ULONG err );
  1785. WINLDAPAPI PCHAR LDAPAPI ldap_err2stringA( ULONG err );
  1786.  
  1787. #if LDAP_UNICODE
  1788.  
  1789. #define ldap_err2string ldap_err2stringW
  1790.  
  1791. #else
  1792.  
  1793. WINLDAPAPI PCHAR LDAPAPI ldap_err2string( ULONG err );
  1794.  
  1795. #endif
  1796.  
  1797. //
  1798. //  ldap_perror does nothing and is here just for compatibility.
  1799. //
  1800.  
  1801. WINLDAPAPI void LDAPAPI ldap_perror( LDAP *ld, PCHAR msg );
  1802.  
  1803. //
  1804. //  Return the first entry of a message.  It is freed when the message is
  1805. //  freed so should not be freed explicitly.
  1806. //
  1807.  
  1808. WINLDAPAPI LDAPMessage *LDAPAPI ldap_first_entry( LDAP *ld, LDAPMessage *res );
  1809.  
  1810. //
  1811. //  Return the next entry of a message.  It is freed when the message is
  1812. //  freed so should not be freed explicitly.
  1813. //
  1814.  
  1815. WINLDAPAPI LDAPMessage *LDAPAPI ldap_next_entry( LDAP *ld, LDAPMessage *entry );
  1816.  
  1817. //
  1818. //  Count the number of search entries returned by the server in a response
  1819. //  to a server request.
  1820. //
  1821.  
  1822. WINLDAPAPI ULONG LDAPAPI ldap_count_entries( LDAP *ld, LDAPMessage *res );
  1823.  
  1824. //
  1825. //  A BerElement really maps out to a C++ class object that does BER encoding.
  1826. //  Don't mess with it as it's opaque.
  1827. //
  1828.  
  1829. typedef struct berelement {
  1830.     PCHAR   opaque;     // this is an opaque structure used just for
  1831.                         // compatibility with reference implementation
  1832. } BerElement;
  1833. #define NULLBER ((BerElement *) 0)
  1834.  
  1835. //
  1836. //  For a given entry, return the first attribute.  The pointer returned is
  1837. //  actually a buffer in the connection block (with allowances for
  1838. //  multi-threaded apps) so it should not be freed.
  1839. //
  1840.  
  1841. WINLDAPAPI PWCHAR LDAPAPI ldap_first_attributeW(
  1842.         LDAP            *ld,
  1843.         LDAPMessage     *entry,
  1844.         BerElement      **ptr
  1845.         );
  1846.  
  1847. WINLDAPAPI PCHAR LDAPAPI ldap_first_attributeA(
  1848.         LDAP            *ld,
  1849.         LDAPMessage     *entry,
  1850.         BerElement      **ptr
  1851.         );
  1852.  
  1853. #if LDAP_UNICODE
  1854.  
  1855. #define ldap_first_attribute ldap_first_attributeW
  1856.  
  1857. #else
  1858.  
  1859. WINLDAPAPI PCHAR LDAPAPI ldap_first_attribute(
  1860.         LDAP            *ld,
  1861.         LDAPMessage     *entry,
  1862.         BerElement      **ptr
  1863.         );
  1864. #endif
  1865.  
  1866. //
  1867. //  Return the next attribute... again, the attribute pointer should not be
  1868. //  freed.
  1869. //
  1870.  
  1871. WINLDAPAPI PWCHAR LDAPAPI ldap_next_attributeW(
  1872.         LDAP            *ld,
  1873.         LDAPMessage     *entry,
  1874.         BerElement      *ptr
  1875.         );
  1876.  
  1877. WINLDAPAPI PCHAR LDAPAPI ldap_next_attributeA(
  1878.         LDAP            *ld,
  1879.         LDAPMessage     *entry,
  1880.         BerElement      *ptr
  1881.         );
  1882.  
  1883.  
  1884. #if LDAP_UNICODE
  1885.  
  1886. #define ldap_next_attribute ldap_next_attributeW
  1887.  
  1888. #else
  1889.  
  1890. WINLDAPAPI PCHAR LDAPAPI ldap_next_attribute(
  1891.         LDAP            *ld,
  1892.         LDAPMessage     *entry,
  1893.         BerElement      *ptr
  1894.         );
  1895. #endif
  1896.  
  1897. //
  1898. //  Get a given attribute's list of values.  This is used during parsing of
  1899. //  a search response.  It returns a list of pointers to values, the list is
  1900. //  null terminated.
  1901. //
  1902. //  If the values are generic octet strings and not null terminated strings,
  1903. //  use ldap_get_values_len instead.
  1904. //
  1905. //  The returned value should be freed when your done with it by calling
  1906. //  ldap_value_free.
  1907. //
  1908.  
  1909. WINLDAPAPI PWCHAR *LDAPAPI ldap_get_valuesW(
  1910.         LDAP            *ld,
  1911.         LDAPMessage     *entry,
  1912.         PWCHAR          attr
  1913.         );
  1914. WINLDAPAPI PCHAR *LDAPAPI ldap_get_valuesA(
  1915.         LDAP            *ld,
  1916.         LDAPMessage     *entry,
  1917.         PCHAR           attr
  1918.         );
  1919.  
  1920. #if LDAP_UNICODE
  1921.  
  1922. #define ldap_get_values ldap_get_valuesW
  1923.  
  1924. #else
  1925.  
  1926. WINLDAPAPI PCHAR *LDAPAPI ldap_get_values(
  1927.         LDAP            *ld,
  1928.         LDAPMessage     *entry,
  1929.         PCHAR           attr
  1930.         );
  1931. #endif
  1932.  
  1933.  
  1934.  
  1935.  
  1936. //
  1937. //  Get a given attribute's list of values.  This is used during parsing of
  1938. //  a search response.  It returns a list of berval structures to values,
  1939. //  the list is null terminated.
  1940. //
  1941. //  If the values are null terminated strings, it may be easier to process them
  1942. //  by calling ldap_get_values instead.
  1943. //
  1944. //  The returned value should be freed when your done with it by calling
  1945. //  ldap_value_free_len.
  1946. //
  1947.  
  1948. WINLDAPAPI struct berval **LDAPAPI ldap_get_values_lenW (
  1949.     LDAP            *ExternalHandle,
  1950.     LDAPMessage     *Message,
  1951.     PWCHAR          attr
  1952.     );
  1953. WINLDAPAPI struct berval **LDAPAPI ldap_get_values_lenA (
  1954.     LDAP            *ExternalHandle,
  1955.     LDAPMessage     *Message,
  1956.     PCHAR           attr
  1957.     );
  1958.  
  1959. #if LDAP_UNICODE
  1960.  
  1961. #define ldap_get_values_len ldap_get_values_lenW
  1962.  
  1963. #else
  1964.  
  1965. WINLDAPAPI struct berval **LDAPAPI ldap_get_values_len (
  1966.     LDAP            *ExternalHandle,
  1967.     LDAPMessage     *Message,
  1968.     PCHAR           attr
  1969.     );
  1970.  
  1971. #endif
  1972.  
  1973.  
  1974. //
  1975. //  Return the number of values in a list returned by ldap_get_values.
  1976. //
  1977.  
  1978. WINLDAPAPI ULONG LDAPAPI ldap_count_valuesW( PWCHAR *vals );
  1979. WINLDAPAPI ULONG LDAPAPI ldap_count_valuesA( PCHAR *vals );
  1980.  
  1981. #if LDAP_UNICODE
  1982.  
  1983. #define ldap_count_values ldap_count_valuesW
  1984.  
  1985. #else
  1986.  
  1987. WINLDAPAPI ULONG LDAPAPI ldap_count_values( PCHAR *vals );
  1988.  
  1989. #endif
  1990.  
  1991.  
  1992.  
  1993. //
  1994. //  Return the number of values in a list returned by ldap_get_values_len.
  1995. //
  1996.  
  1997. WINLDAPAPI ULONG LDAPAPI ldap_count_values_len( struct berval **vals );
  1998.  
  1999. //
  2000. //  Free structures returned by ldap_get_values.
  2001. //
  2002.  
  2003. WINLDAPAPI ULONG LDAPAPI ldap_value_freeW( PWCHAR *vals );
  2004. WINLDAPAPI ULONG LDAPAPI ldap_value_freeA( PCHAR *vals );
  2005.  
  2006. #if LDAP_UNICODE
  2007.  
  2008. #define ldap_value_free ldap_value_freeW
  2009.  
  2010. #else
  2011.  
  2012. WINLDAPAPI ULONG LDAPAPI ldap_value_free( PCHAR *vals );
  2013.  
  2014. #endif
  2015.  
  2016.  
  2017.  
  2018. //
  2019. //  Free structures returned by ldap_get_values_len.
  2020. //
  2021.  
  2022. WINLDAPAPI ULONG LDAPAPI ldap_value_free_len( struct berval **vals );
  2023.  
  2024. //
  2025. //  Get the distinguished name for a given search entry.  It should be freed
  2026. //  by calling ldap_memfree.
  2027. //
  2028.  
  2029. WINLDAPAPI PWCHAR LDAPAPI ldap_get_dnW( LDAP *ld, LDAPMessage *entry );
  2030. WINLDAPAPI PCHAR LDAPAPI ldap_get_dnA( LDAP *ld, LDAPMessage *entry );
  2031.  
  2032. #if LDAP_UNICODE
  2033.  
  2034. #define ldap_get_dn ldap_get_dnW
  2035.  
  2036. #else
  2037.  
  2038. WINLDAPAPI PCHAR LDAPAPI ldap_get_dn( LDAP *ld, LDAPMessage *entry );
  2039.  
  2040. #endif
  2041.  
  2042.  
  2043. //
  2044. //  When using ldap_explode_dn, you should free the returned string by
  2045. //  calling ldap_value_free.
  2046. //
  2047.  
  2048. WINLDAPAPI PWCHAR *LDAPAPI ldap_explode_dnW( PWCHAR dn, ULONG notypes );
  2049. WINLDAPAPI PCHAR *LDAPAPI ldap_explode_dnA( PCHAR dn, ULONG notypes );
  2050.  
  2051. #if LDAP_UNICODE
  2052.  
  2053. #define ldap_explode_dn ldap_explode_dnW
  2054.  
  2055. #else
  2056.  
  2057. WINLDAPAPI PCHAR *LDAPAPI ldap_explode_dn( PCHAR dn, ULONG notypes );
  2058.  
  2059. #endif
  2060.  
  2061.  
  2062. //
  2063. //  When calling ldap_dn2ufn, you should free the returned string by calling
  2064. //  ldap_memfree.
  2065. //
  2066.  
  2067. WINLDAPAPI PWCHAR LDAPAPI ldap_dn2ufnW( PWCHAR dn );
  2068. WINLDAPAPI PCHAR LDAPAPI ldap_dn2ufnA( PCHAR dn );
  2069.  
  2070. #if LDAP_UNICODE
  2071.  
  2072. #define ldap_dn2ufn ldap_dn2ufnW
  2073.  
  2074. #else
  2075.  
  2076. WINLDAPAPI PCHAR LDAPAPI ldap_dn2ufn( PCHAR dn );
  2077.  
  2078. #endif
  2079.  
  2080.  
  2081.  
  2082. //
  2083. //  This is used to free strings back to the LDAP API heap.  Don't pass in
  2084. //  values that you've gotten from ldap_open, ldap_get_values, etc.
  2085. //
  2086.  
  2087. WINLDAPAPI VOID LDAPAPI ldap_memfreeW( PWCHAR Block );
  2088. WINLDAPAPI VOID LDAPAPI ldap_memfreeA( PCHAR Block );
  2089.  
  2090. WINLDAPAPI VOID LDAPAPI ber_bvfree( struct berval *bv );
  2091.  
  2092. #if LDAP_UNICODE
  2093.  
  2094. #define ldap_memfree ldap_memfreeW
  2095.  
  2096. #else
  2097.  
  2098. WINLDAPAPI VOID LDAPAPI ldap_memfree( PCHAR Block );
  2099.  
  2100. #endif
  2101.  
  2102.  
  2103. //
  2104. //  The function ldap_ufn2dn attempts to "normalize" a user specified DN
  2105. //  to make it "proper".  It follows RFC 1781 (add CN= if not present,
  2106. //  add OU= if none present, etc).  If it runs into any problems at all
  2107. //  while normalizing, it simply returns a copy of what was passed in.
  2108. //
  2109. //  It allocates the output string from the LDAP memory pool.  If the pDn
  2110. //  comes back as non-NULL, you should free it when you're done with a call
  2111. //  to ldap_memfree.
  2112. //
  2113.  
  2114. WINLDAPAPI ULONG LDAPAPI ldap_ufn2dnW (
  2115.     PWCHAR ufn,
  2116.     PWCHAR *pDn
  2117.     );
  2118. WINLDAPAPI ULONG LDAPAPI ldap_ufn2dnA (
  2119.     PCHAR ufn,
  2120.     PCHAR *pDn
  2121.     );
  2122.  
  2123. #if LDAP_UNICODE
  2124.  
  2125. #define ldap_ufn2dn ldap_ufn2dnW
  2126.  
  2127. #else
  2128.  
  2129. WINLDAPAPI ULONG LDAPAPI ldap_ufn2dn (
  2130.     PCHAR ufn,
  2131.     PCHAR *pDn
  2132.     );
  2133.  
  2134. #endif
  2135.  
  2136. #define LBER_USE_DER        0x01
  2137. #define LBER_USE_INDEFINITE_LEN 0x02
  2138. #define LBER_TRANSLATE_STRINGS  0x04
  2139.  
  2140. //
  2141. //  Call to initialize the LDAP library.  Pass in a version structure with
  2142. //  lv_size set to sizeof( LDAP_VERSION ), lv_major set to LAPI_MAJOR_VER1,
  2143. //  and lv_minor set to LAPI_MINOR_VER1.  Return value will be either
  2144. //  LDAP_SUCCESS if OK or LDAP_OPERATIONS_ERROR if can't be supported.
  2145. //
  2146.  
  2147. #define LAPI_MAJOR_VER1     1
  2148. #define LAPI_MINOR_VER1     1
  2149.  
  2150. typedef struct ldap_version_info {
  2151.      ULONG   lv_size;
  2152.      ULONG   lv_major;
  2153.      ULONG   lv_minor;
  2154. } LDAP_VERSION_INFO, *PLDAP_VERSION_INFO;
  2155.  
  2156. WINLDAPAPI ULONG LDAPAPI ldap_startup (
  2157.     PLDAP_VERSION_INFO version,
  2158.     HANDLE *Instance
  2159.     );
  2160.  
  2161. //
  2162. //  ldap_cleanup unloads the library when the refcount of opens goes to zero.
  2163. //  (i.e. if a DLL calls it within a program that is also using it, it won't
  2164. //  free all resources)
  2165. //
  2166.  
  2167. WINLDAPAPI ULONG LDAPAPI ldap_cleanup (
  2168.     HANDLE hInstance
  2169.     );
  2170.  
  2171. //
  2172. //  Extended API to support allowing opaque blobs of data in search filters.
  2173. //  This API takes any filter element and converts it to a safe text string that
  2174. //  can safely be passed in a search filter.
  2175. //  An example of using this is :
  2176. //
  2177. //  filter is something like guid=4826BF6CF0123444
  2178. //  this will put out on the wire guid of binary 0x4826BF6CF0123444
  2179. //
  2180. //  call ldap_escape_filter_element with sourceFilterElement pointing to
  2181. //  raw data, sourceCount set appropriately to length of data.
  2182. //
  2183. //  if destFilterElement is NULL, then return value is length required for
  2184. //  output buffer.
  2185. //
  2186. //  if destFilterElement is not NULL, then the function will copy the source
  2187. //  into the dest buffer and ensure that it is of a safe format.
  2188. //
  2189. //  then simply insert the dest buffer into your search filter after the
  2190. //  "attributetype=".
  2191. //
  2192. //  this will put out on the wire guid of binary 0x004826BF6CF000123444
  2193. //
  2194. //  Note : don't call this for attribute values that are really strings, as
  2195. //  we won't do any conversion from what you passed in to UTF-8.  Should only
  2196. //  be used for attributes that really are raw binary.
  2197. //
  2198.  
  2199. WINLDAPAPI ULONG LDAPAPI ldap_escape_filter_elementW (
  2200.    PCHAR   sourceFilterElement,
  2201.    ULONG   sourceLength,
  2202.    PWCHAR   destFilterElement,
  2203.    ULONG   destLength
  2204.    );
  2205. WINLDAPAPI ULONG LDAPAPI ldap_escape_filter_elementA (
  2206.    PCHAR   sourceFilterElement,
  2207.    ULONG   sourceLength,
  2208.    PCHAR   destFilterElement,
  2209.    ULONG   destLength
  2210.    );
  2211.  
  2212. #if LDAP_UNICODE
  2213.  
  2214. #define ldap_escape_filter_element ldap_escape_filter_elementW
  2215.  
  2216. #else
  2217.  
  2218. WINLDAPAPI ULONG LDAPAPI ldap_escape_filter_element (
  2219.    PCHAR   sourceFilterElement,
  2220.    ULONG   sourceLength,
  2221.    PCHAR   destFilterElement,
  2222.    ULONG   destLength
  2223.    );
  2224.  
  2225. #endif
  2226.  
  2227. //
  2228. //  Misc extensions for additional debugging.
  2229. //
  2230. //  Note that these do nothing on free builds.
  2231. //
  2232.  
  2233. WINLDAPAPI ULONG LDAPAPI ldap_set_dbg_flags( ULONG NewFlags );
  2234.  
  2235. typedef ULONG (_cdecl *DBGPRINT)( PCH Format, ... );
  2236.  
  2237. WINLDAPAPI VOID LDAPAPI ldap_set_dbg_routine( DBGPRINT DebugPrintRoutine );
  2238.  
  2239. //
  2240. //  These routines are possibly useful by other modules.  Note that Win95
  2241. //  doesn't by default have the UTF-8 codepage loaded.  So a good way to
  2242. //  convert from UTF-8 to Unicode.
  2243. //
  2244.  
  2245.  
  2246. WINLDAPAPI int LDAPAPI
  2247. LdapUTF8ToUnicode(
  2248.     LPCSTR lpSrcStr,
  2249.     int cchSrc,
  2250.     LPWSTR lpDestStr,
  2251.     int cchDest
  2252.     );
  2253.  
  2254. WINLDAPAPI
  2255. int LDAPAPI
  2256. LdapUnicodeToUTF8(
  2257.     LPCWSTR lpSrcStr,
  2258.     int cchSrc,
  2259.     LPSTR lpDestStr,
  2260.     int cchDest
  2261.     );
  2262.  
  2263. //
  2264. //  LDAPv3 features :
  2265. //
  2266. //  Sort Keys... these are used to ask the server to sort the results
  2267. //  before sending the results back.  LDAPv3 only and optional to implement
  2268. //  on the server side.  Check supportedControl for an OID of
  2269. //  "1.2.840.113556.1.4.473" to see if the server supports it.
  2270. //
  2271.  
  2272. #define LDAP_SERVER_SORT_OID "1.2.840.113556.1.4.473"
  2273. #define LDAP_SERVER_SORT_OID_W L"1.2.840.113556.1.4.473"
  2274.  
  2275. #define LDAP_SERVER_RESP_SORT_OID "1.2.840.113556.1.4.474"
  2276. #define LDAP_SERVER_RESP_SORT_OID_W L"1.2.840.113556.1.4.474"
  2277.  
  2278. typedef struct ldapsearch LDAPSearch, *PLDAPSearch;
  2279.  
  2280. typedef struct ldapsortkeyW {
  2281.  
  2282.     PWCHAR  sk_attrtype;
  2283.     PWCHAR  sk_matchruleoid;
  2284.     BOOLEAN sk_reverseorder;
  2285.  
  2286. } LDAPSortKeyW, *PLDAPSortKeyW;
  2287.  
  2288. typedef struct ldapsortkeyA {
  2289.  
  2290.     PCHAR   sk_attrtype;
  2291.     PCHAR   sk_matchruleoid;
  2292.     BOOLEAN sk_reverseorder;
  2293.  
  2294. } LDAPSortKeyA, *PLDAPSortKeyA;
  2295.  
  2296. #if LDAP_UNICODE
  2297. #define LDAPSortKey LDAPSortKeyW
  2298. #define PLDAPSortKey PLDAPSortKeyW
  2299. #else
  2300. #define LDAPSortKey LDAPSortKeyA
  2301. #define PLDAPSortKey PLDAPSortKeyA
  2302. #endif
  2303.  
  2304. //
  2305. //  This API formats a list of sort keys into a search control.  Call
  2306. //  ldap_control_free when you're finished with the control.
  2307. //
  2308. //  Use this one rather than ldap_encode_sort_control as this is per RFC.
  2309. //
  2310.  
  2311. WINLDAPAPI ULONG LDAPAPI ldap_create_sort_controlA (
  2312.         PLDAP           ExternalHandle,
  2313.         PLDAPSortKeyA  *SortKeys,
  2314.         UCHAR           IsCritical,
  2315.         PLDAPControlA  *Control
  2316.         );
  2317.  
  2318. WINLDAPAPI ULONG LDAPAPI ldap_create_sort_controlW (
  2319.         PLDAP           ExternalHandle,
  2320.         PLDAPSortKeyW  *SortKeys,
  2321.         UCHAR           IsCritical,
  2322.         PLDAPControlW  *Control
  2323.         );
  2324.  
  2325. //
  2326. //  This API parses the sort control returned by the server.  Use ldap_memfree
  2327. //  to free the attribute value, if it's returned.
  2328. //
  2329.  
  2330. WINLDAPAPI ULONG LDAPAPI ldap_parse_sort_controlA (
  2331.         PLDAP           ExternalHandle,
  2332.         PLDAPControlA  *Control,
  2333.         ULONG          *Result,
  2334.         PCHAR          *Attribute
  2335.         );
  2336.  
  2337. WINLDAPAPI ULONG LDAPAPI ldap_parse_sort_controlW (
  2338.         PLDAP           ExternalHandle,
  2339.         PLDAPControlW  *Control,
  2340.         ULONG          *Result,
  2341.         PWCHAR         *Attribute
  2342.         );
  2343.  
  2344. #if LDAP_UNICODE
  2345.  
  2346. #define ldap_create_sort_control ldap_create_sort_controlW
  2347. #define ldap_parse_sort_control ldap_parse_sort_controlW
  2348.  
  2349. #else
  2350.  
  2351. WINLDAPAPI ULONG LDAPAPI ldap_create_sort_control (
  2352.         PLDAP           ExternalHandle,
  2353.         PLDAPSortKeyA  *SortKeys,
  2354.         UCHAR           IsCritical,
  2355.         PLDAPControlA  *Control
  2356.         );
  2357.  
  2358. WINLDAPAPI ULONG LDAPAPI ldap_parse_sort_control (
  2359.         PLDAP           ExternalHandle,
  2360.         PLDAPControlA  *Control,
  2361.         ULONG          *Result,
  2362.         PCHAR          *Attribute
  2363.         );
  2364. #endif
  2365.  
  2366. //
  2367. //  This API formats a list of sort keys into a search control.  Call
  2368. //  ldap_memfree for both Control->ldctl_value.bv_val and
  2369. //  Control->currentControl->ldctl_oid when you're finished with the control.
  2370. //
  2371. //  This is the old sort API that will be shortly pulled.  Please use
  2372. //  ldap_create_sort_control defined above.
  2373. //
  2374.  
  2375. WINLDAPAPI ULONG LDAPAPI ldap_encode_sort_controlW (
  2376.         PLDAP           ExternalHandle,
  2377.         PLDAPSortKeyW  *SortKeys,
  2378.         PLDAPControlW  Control,
  2379.         BOOLEAN Criticality
  2380.         );
  2381.  
  2382. WINLDAPAPI ULONG LDAPAPI ldap_encode_sort_controlA (
  2383.         PLDAP           ExternalHandle,
  2384.         PLDAPSortKeyA  *SortKeys,
  2385.         PLDAPControlA  Control,
  2386.         BOOLEAN Criticality
  2387.         );
  2388.  
  2389. #if LDAP_UNICODE
  2390.  
  2391. #define ldap_encode_sort_control ldap_encode_sort_controlW
  2392.  
  2393. #else
  2394.  
  2395. WINLDAPAPI ULONG LDAPAPI ldap_encode_sort_control (
  2396.         PLDAP           ExternalHandle,
  2397.         PLDAPSortKeyA  *SortKeys,
  2398.         PLDAPControlA  Control,
  2399.         BOOLEAN Criticality
  2400.         );
  2401. #endif
  2402.  
  2403. //
  2404. //  LDAPv3: This is the RFC defined API for the simple paging of results
  2405. //  control.  Use ldap_control_free to free the control allocated by
  2406. //  ldap_create_page_control.
  2407. //
  2408.  
  2409. WINLDAPAPI ULONG LDAPAPI ldap_create_page_controlW(
  2410.         PLDAP           ExternalHandle,
  2411.         ULONG           PageSize,
  2412.         struct berval  *Cookie,
  2413.         UCHAR           IsCritical,
  2414.         PLDAPControlW  *Control
  2415.         );
  2416.  
  2417. WINLDAPAPI ULONG LDAPAPI ldap_create_page_controlA(
  2418.         PLDAP           ExternalHandle,
  2419.         ULONG           PageSize,
  2420.         struct berval  *Cookie,
  2421.         UCHAR           IsCritical,
  2422.         PLDAPControlA  *Control
  2423.         );
  2424.  
  2425. WINLDAPAPI ULONG LDAPAPI ldap_parse_page_controlW (
  2426.         PLDAP           ExternalHandle,
  2427.         PLDAPControlW  *ServerControls,
  2428.         ULONG          *TotalCount,
  2429.         struct berval  **Cookie     // Use ber_bvfree to free
  2430.         );
  2431.  
  2432. WINLDAPAPI ULONG LDAPAPI ldap_parse_page_controlA (
  2433.         PLDAP           ExternalHandle,
  2434.         PLDAPControlA  *ServerControls,
  2435.         ULONG          *TotalCount,
  2436.         struct berval  **Cookie     // Use ber_bvfree to free
  2437.         );
  2438.  
  2439. #if LDAP_UNICODE
  2440.  
  2441. #define ldap_create_page_control ldap_create_page_controlW
  2442. #define ldap_parse_page_control  ldap_parse_page_controlW
  2443.  
  2444. #else
  2445.  
  2446. WINLDAPAPI ULONG LDAPAPI ldap_create_page_control(
  2447.         PLDAP           ExternalHandle,
  2448.         ULONG           PageSize,
  2449.         struct berval  *Cookie,
  2450.         UCHAR           IsCritical,
  2451.         PLDAPControlA  *Control
  2452.         );
  2453.  
  2454. WINLDAPAPI ULONG LDAPAPI ldap_parse_page_control (
  2455.         PLDAP           ExternalHandle,
  2456.         PLDAPControlA  *ServerControls,
  2457.         ULONG          *TotalCount,
  2458.         struct berval  **Cookie     // Use ber_bvfree to free
  2459.         );
  2460. #endif
  2461.  
  2462. //
  2463. //  LDAPv3: This is the interface for simple paging of results.  To ensure
  2464. //  that the server supports it, check the supportedControl property off of
  2465. //  the root for an OID of 1.2.840.113556.1.4.319.  If it is there, then it
  2466. //  supports this feature.
  2467. //
  2468. //  If you're going to specify sort keys, see section above on sort keys on
  2469. //  now to tell if they're supported by the server.
  2470. //
  2471. //  You first call ldap_search_init_page.  If it returns a non-NULL LDAPSearch
  2472. //  block, then it worked ok.  Otherwise call LdapGetLastError to find error.
  2473. //
  2474. //  With a valid LDAPSearch block (there are opaque), call ldap_get_next_page
  2475. //  or ldap_get_next_page_s.  If you call ldap_get_next_page, you MUST call
  2476. //  ldap_get_paged_count for each set of results that you get for that message.
  2477. //  This allows the library to save off the cookie that the server sent to
  2478. //  resume the search.
  2479. //
  2480. //  Other than calling ldap_get_paged_count, the results you get back from
  2481. //  ldap_get_next_page can be treated as any other search result, and should
  2482. //  be freed when you're done by calling ldap_msgfree.
  2483. //
  2484. //  When the end of the search is hit, you'll get a return code of
  2485. //  LDAP_NO_RESULTS_RETURNED.  At this point, (or any point after LDAPSearch
  2486. //  structure has been allocated), you call ldap_search_abandon_page.  You
  2487. //  need to call this even after you get a return code of
  2488. //  LDAP_NO_RESULTS_RETURNED.
  2489. //
  2490. //  If you call ldap_get_next_page_s, you don't need to call
  2491. //  ldap_get_paged_count.
  2492. //
  2493.  
  2494. #define LDAP_PAGED_RESULT_OID_STRING "1.2.840.113556.1.4.319"
  2495. #define LDAP_PAGED_RESULT_OID_STRING_W L"1.2.840.113556.1.4.319"
  2496.  
  2497. WINLDAPAPI PLDAPSearch LDAPAPI ldap_search_init_pageW(
  2498.         PLDAP           ExternalHandle,
  2499.         PWCHAR          DistinguishedName,
  2500.         ULONG           ScopeOfSearch,
  2501.         PWCHAR          SearchFilter,
  2502.         PWCHAR          AttributeList[],
  2503.         ULONG           AttributesOnly,
  2504.         PLDAPControlW   *ServerControls,
  2505.         PLDAPControlW   *ClientControls,
  2506.         ULONG           PageTimeLimit,
  2507.         ULONG           TotalSizeLimit,
  2508.         PLDAPSortKeyW  *SortKeys
  2509.     );
  2510.  
  2511. WINLDAPAPI PLDAPSearch LDAPAPI ldap_search_init_pageA(
  2512.         PLDAP           ExternalHandle,
  2513.         PCHAR           DistinguishedName,
  2514.         ULONG           ScopeOfSearch,
  2515.         PCHAR           SearchFilter,
  2516.         PCHAR           AttributeList[],
  2517.         ULONG           AttributesOnly,
  2518.         PLDAPControlA   *ServerControls,
  2519.         PLDAPControlA   *ClientControls,
  2520.         ULONG           PageTimeLimit,
  2521.         ULONG           TotalSizeLimit,
  2522.         PLDAPSortKeyA  *SortKeys
  2523.     );
  2524.  
  2525. #if LDAP_UNICODE
  2526.  
  2527. #define ldap_search_init_page ldap_search_init_pageW
  2528.  
  2529. #else
  2530.  
  2531. WINLDAPAPI PLDAPSearch LDAPAPI ldap_search_init_page(
  2532.         PLDAP           ExternalHandle,
  2533.         PCHAR           DistinguishedName,
  2534.         ULONG           ScopeOfSearch,
  2535.         PCHAR           SearchFilter,
  2536.         PCHAR           AttributeList[],
  2537.         ULONG           AttributesOnly,
  2538.         PLDAPControlA   *ServerControls,
  2539.         PLDAPControlA   *ClientControls,
  2540.         ULONG           PageTimeLimit,
  2541.         ULONG           TotalSizeLimit,
  2542.         PLDAPSortKeyA  *SortKeys
  2543.     );
  2544.  
  2545. #endif
  2546.  
  2547. WINLDAPAPI ULONG LDAPAPI ldap_get_next_page(
  2548.         PLDAP           ExternalHandle,
  2549.         PLDAPSearch     SearchHandle,
  2550.         ULONG           PageSize,
  2551.         ULONG          *MessageNumber
  2552.     );
  2553.  
  2554. WINLDAPAPI ULONG LDAPAPI ldap_get_next_page_s(
  2555.         PLDAP           ExternalHandle,
  2556.         PLDAPSearch     SearchHandle,
  2557.         struct l_timeval  *timeout,
  2558.         ULONG           PageSize,
  2559.         ULONG          *TotalCount,
  2560.         LDAPMessage     **Results
  2561.     );
  2562.  
  2563. WINLDAPAPI ULONG LDAPAPI ldap_get_paged_count(
  2564.         PLDAP           ExternalHandle,
  2565.         PLDAPSearch     SearchBlock,
  2566.         ULONG          *TotalCount,
  2567.         PLDAPMessage    Results
  2568.     );
  2569.  
  2570. WINLDAPAPI ULONG LDAPAPI ldap_search_abandon_page(
  2571.         PLDAP           ExternalHandle,
  2572.         PLDAPSearch     SearchBlock
  2573.     );
  2574.  
  2575. //
  2576. //  These functions return subordinate referrals (references) that are returned
  2577. //  in search responses.  There are two types of referrals.  External referrals
  2578. //  where the naming context doesn't reside on the server (e.g. server says "I
  2579. //  don't have the data, look over there") and Subordinate referrals (or
  2580. //  references) where some data has been returned and the referrals are passed
  2581. //  to other naming contexts below the current one (e.g. servers says "Here's
  2582. //  some data from the tree I hold, go look here, there, and over there for
  2583. //  more data that is further down in the tree.").
  2584. //
  2585. //  These routines handle the latter.  For external references, use
  2586. //  ldap_parse_result.
  2587. //
  2588. //  Return the first reference from a message.  It is freed when the message is
  2589. //  freed so should not be freed explicitly.
  2590. //
  2591.  
  2592. WINLDAPAPI LDAPMessage *LDAPAPI ldap_first_reference( LDAP *ld, LDAPMessage *res );
  2593.  
  2594. //
  2595. //  Return the next entry of a message.  It is freed when the message is
  2596. //  freed so should not be freed explicitly.
  2597. //
  2598.  
  2599. WINLDAPAPI LDAPMessage *LDAPAPI ldap_next_reference( LDAP *ld, LDAPMessage *entry );
  2600.  
  2601. //
  2602. //  Count the number of subordinate references returned by the server in a
  2603. //  response to a search request.
  2604. //
  2605.  
  2606. WINLDAPAPI ULONG LDAPAPI ldap_count_references( LDAP *ld, LDAPMessage *res );
  2607.  
  2608. //
  2609. //  We return the list of subordinate referrals in a search response message.
  2610. //
  2611.  
  2612. WINLDAPAPI ULONG LDAPAPI ldap_parse_referenceW (
  2613.         LDAP *Connection,
  2614.         LDAPMessage *ResultMessage,
  2615.         PWCHAR **Referrals                   // free with ldap_value_freeW
  2616.         );
  2617.  
  2618. WINLDAPAPI ULONG LDAPAPI ldap_parse_referenceA (
  2619.         LDAP *Connection,
  2620.         LDAPMessage *ResultMessage,
  2621.         PCHAR **Referrals                   // free with ldap_value_freeA
  2622.         );
  2623.  
  2624. #if LDAP_UNICODE
  2625.  
  2626. #define ldap_parse_reference ldap_parse_referenceW
  2627.  
  2628. #else
  2629.  
  2630. WINLDAPAPI ULONG LDAPAPI ldap_parse_reference (
  2631.         LDAP *Connection,
  2632.         LDAPMessage *ResultMessage,
  2633.         PCHAR **Referrals                   // free with ldap_value_free
  2634.         );
  2635.  
  2636. #endif
  2637.  
  2638.  
  2639. //
  2640. //  These APIs allow a client to send an extended request (free for all) to
  2641. //  an LDAPv3 (or above) server.  The functionality is fairly open... you can
  2642. //  send any request you'd like.  Note that since we don't know if you'll
  2643. //  be receiving a single or multiple responses, you'll have to explicitly tell
  2644. //  us when you're done with the request by calling ldap_close_extended_op.
  2645. //
  2646. //  These are thread safe.
  2647. //
  2648.  
  2649. WINLDAPAPI ULONG LDAPAPI ldap_extended_operationW(
  2650.         LDAP *ld,
  2651.         PWCHAR Oid,
  2652.         struct berval   *Data,
  2653.         PLDAPControlW   *ServerControls,
  2654.         PLDAPControlW   *ClientControls,
  2655.         ULONG           *MessageNumber
  2656.         );
  2657.  
  2658. WINLDAPAPI ULONG LDAPAPI ldap_extended_operationA(
  2659.         LDAP *ld,
  2660.         PCHAR Oid,
  2661.         struct berval   *Data,
  2662.         PLDAPControlA   *ServerControls,
  2663.         PLDAPControlA   *ClientControls,
  2664.         ULONG           *MessageNumber
  2665.         );
  2666.  
  2667. #if LDAP_UNICODE
  2668.  
  2669. #define ldap_extended_operation ldap_extended_operationW
  2670.  
  2671. #else
  2672.  
  2673. WINLDAPAPI ULONG LDAPAPI ldap_extended_operation(
  2674.         LDAP *ld,
  2675.         PCHAR Oid,
  2676.         struct berval   *Data,
  2677.         PLDAPControlA   *ServerControls,
  2678.         PLDAPControlA   *ClientControls,
  2679.         ULONG           *MessageNumber
  2680.         );
  2681. #endif
  2682.  
  2683. WINLDAPAPI ULONG LDAPAPI ldap_close_extended_op(
  2684.         LDAP    *ld,
  2685.         ULONG   MessageNumber
  2686.         );
  2687.  
  2688.  
  2689. //
  2690. //  Some enhancements that will probably never make it into the RFC related
  2691. //  to callouts to allow external caching of connections.
  2692. //
  2693. //  Call ldap_set_option( conn, LDAP_OPT_REFERRAL_CALLBACK, &referralRoutines )
  2694. //  where referralRoutines is the address of an LDAP_REFERRAL_CALLBACK
  2695. //  structure with your routines.  They may be NULL, in which case we'll
  2696. //  obviously not make the calls.
  2697. //
  2698. //  Any connections that are created will inherit the current callbacks from
  2699. //  the primary connection that the request was initiated on.
  2700. //
  2701.  
  2702. #define LDAP_OPT_REFERRAL_CALLBACK  0x70
  2703.  
  2704. //
  2705. //  This first routine is called when we're about to chase a referral.  We
  2706. //  callout to it to see if there is already a connection cached that we
  2707. //  can use.  If so, the callback routine returns the pointer to the
  2708. //  connection to use in ConnectionToUse.  If not, it sets
  2709. //  *ConnectionToUse to NULL.
  2710. //
  2711. //  For a return code, it should return 0 if we should continue to chase the
  2712. //  referral.  If it returns a non-zero return code, we'll treat that as the
  2713. //  error code for chasing the referral.  This allows caching of host names
  2714. //  that are not reachable, if we decide to add that in the future.
  2715. //
  2716.  
  2717. typedef ULONG (_cdecl QUERYFORCONNECTION)(
  2718.     PLDAP       PrimaryConnection,
  2719.     PLDAP       ReferralFromConnection,
  2720.     PWCHAR      NewDN,
  2721.     PCHAR       HostName,
  2722.     ULONG       PortNumber,
  2723.     PVOID       SecAuthIdentity,    // if null, use CurrentUser below
  2724.     PVOID       CurrentUserToken,   // pointer to current user's LUID
  2725.     PLDAP       *ConnectionToUse
  2726.     );
  2727.  
  2728. //
  2729. //  This next function is called when we've created a new connection while
  2730. //  chasing a referral.  Note that it gets assigned the same callback functions
  2731. //  as the PrimaryConnection.  If the return code is FALSE, then the call
  2732. //  back function doesn't want to cache the connection and it will be
  2733. //  destroyed after the operation is complete.  If TRUE is returned, we'll
  2734. //  assume that the callee has taken ownership of the connection and it will
  2735. //  not be destroyed after the operation is complete.
  2736. //
  2737. //  If the ErrorCodeFromBind field is not 0, then the bind operation to
  2738. //  that server failed.
  2739. //
  2740.  
  2741. typedef BOOLEAN (_cdecl NOTIFYOFNEWCONNECTION) (
  2742.     PLDAP       PrimaryConnection,
  2743.     PLDAP       ReferralFromConnection,
  2744.     PWCHAR      NewDN,
  2745.     PCHAR       HostName,
  2746.     PLDAP       NewConnection,
  2747.     ULONG       PortNumber,
  2748.     PVOID       SecAuthIdentity,    // if null, use CurrentUser below
  2749.     PVOID       CurrentUser,        // pointer to current user's LUID
  2750.     ULONG       ErrorCodeFromBind
  2751.     );
  2752.  
  2753. //
  2754. //  This next function is called when we've successfully called off to the
  2755. //  QueryForConnection call and received a connection OR when we called off
  2756. //  to the NotifyOfNewConnection call and it returned TRUE.  We call this
  2757. //  function when we're dereferencing the connection after we're done with it.
  2758. //
  2759. //  Return code is currently ignored, but the function should return
  2760. //  LDAP_SUCCESS if all went well.
  2761. //
  2762.  
  2763. typedef ULONG (_cdecl DEREFERENCECONNECTION)(
  2764.     PLDAP       PrimaryConnection,
  2765.     PLDAP       ConnectionToDereference
  2766.     );
  2767.  
  2768. typedef struct LdapReferralCallback {
  2769.  
  2770.     ULONG   SizeOfCallbacks;        // set to sizeof( LDAP_REFERRAL_CALLBACK )
  2771.     QUERYFORCONNECTION *QueryForConnection;
  2772.     NOTIFYOFNEWCONNECTION *NotifyRoutine;
  2773.     DEREFERENCECONNECTION *DereferenceRoutine;
  2774.  
  2775. } LDAP_REFERRAL_CALLBACK, *PLDAP_REFERRAL_CALLBACK;
  2776.  
  2777. //
  2778. //  Thread Safe way to get last error code returned by LDAP API is to call
  2779. //  LdapGetLastError();
  2780. //
  2781.  
  2782. WINLDAPAPI ULONG LDAPAPI LdapGetLastError( VOID );
  2783.  
  2784. //
  2785. //  Translate from LdapError to closest Win32 error code.
  2786. //
  2787.  
  2788. WINLDAPAPI ULONG LDAPAPI LdapMapErrorToWin32( ULONG LdapError );
  2789.  
  2790. #ifdef __cplusplus
  2791. }
  2792. #endif
  2793.  
  2794. #pragma option pop /*P_O_Pop*/
  2795. #endif  // LDAP_CLIENT_DEFINED
  2796.