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