Table of Contents
LDAP4D at A Dog And His Boy

LDAP4D - Protocol Messages

   

About this section...

This section describes the methods used to perform the protocol operations specified in RFC 2251 LDAP v3. These methods generate BER encoded text that can be used with LDAP_Message_Send to request an action from an LDAP server. Some aspects of LDAP v3 are not yet implemented. These differences are described in .....



LDAP_BindRequest

Syntax:

result := LDAP_BindRequest (distinguishedName;T ; {password:T }; {version:LI} )

Description:

Create a bind message.

Warning:

none

Note:

If no version parameter is passed, it defaults to version 3. Also, SASL Authentication option is NOT supported.

Params:

In/Out

Parameter

Type

   

Example or note

->

distinguished name

Text

The distinguished name of the user. If none is passed then it is treated as an anonymous login.

user=tswenson, o=dogboy, c=US

->

password

Text

The password for the given distinguished name. Usually, a blank string ("") is used if logging in as an anonymous user.

optional parameter

->

version

Longint

Only valid values are 2 or 3, if something else is passed it defaults to 3.

optional parameter

<-

result

Text

BER encoded content of Bind message

 

Example:

$tText := LDAP_BindRequest($tDN;$tPassword;$iVersion)
If ($tText = "")  `could check result code also...
  ALERT("Couldn't create Bind request!")
End If


LDAP_UnbindRequest

Syntax:

result:= LDAP_UnbindRequest

Description:

Create a unbind message.

Warning:

none

Note:

 

Params:

In/Out

Parameter

Type

 

Example or note

None
<-

result

Text

BER encoded content of UnbindRequest message

 

Example:

$tText := LDAP_UnbindRequest
If ($tText = "")
  ALERT("Couldn't generate Unbind request!")
End If


LDAP_AbandonRequest

Syntax:

result := LDAP_AbandonRequest (messageID:LI)

Description:

Create an AbandonRequest. Message should have already been sent to the server.

The function of the Abandon Operation is to allow a client to request
that the server abandon an outstanding operation.

The MessageID MUST be that of a an operation which was requested
earlier in this connection.

(The abandon request itself has its own message id. This is distinct
from the id of the earlier operation being abandoned.)

There is no response defined in the Abandon Operation. Upon
transmission of an Abandon Operation, a client may expect that the
operation identified by the Message ID in the Abandon Request has
been abandoned. In the event that a server receives an Abandon
Request on a Search Operation in the midst of transmitting responses
to the search, that server MUST cease transmitting entry responses to
the abandoned request immediately, and MUST NOT send the
SearchResponseDone. Of course, the server MUST ensure that only
properly encoded LDAPMessage PDUs are transmitted.

Warning:

none

Note:

 

Params:

In/Out

Parameter

Type

   

Example or note

->

messageID

Longint

Must be the message ID of a previously generated message that was sent to an LDAP server.

 

<-

result

Text

BER encoded content of AbandonRequest message

 

Example:

$text :=LDAP_AbandonRequest($iMessageID)
If ($tText = "")
  ALERT("Couldn't create Abandon request!")
End IF



LDAP_AddRequest

Syntax:

result := LDAP_AddRequest (distinguishedName;T ; pAttributeTypes:P ; pAttributeValues:P )

Description:

Create an AddRequest.

Warning:

Only single attribute values are supported. 2D text array of attribute values required for v20 and higher

Note:

The arrays of attribute types and attribute values must be of the same length.

Params:

In/Out

Parameter

Type

   

Example or note

->

distinguishedName

Text

distinguished name of the entry to be added.

 

->

pAttributeTypes

Pointer

pointer to a text array of attribute types

 

->

pAttributeValues

Pointer

pointer to a text array of attribute values

 

<-

result

Text

BER encoded content of AddRequest message

 

Example:

$tText :=LDAP_AddRequest("uid=tswenson, o=dogboy";->at_attributeArray;->at_attributeValues)
If ($tText = "")  `could check result code also...
  ALERT("Couldn't create Add request!")
End If



LDAP_DeleteRequest

Syntax:

result := LDAP_DeleteRequest (distinguishedName;T )

Description:

Create a delete request.

Warning:

 

Note:

 

Params:

In/Out

Parameter

Type

   

Example or note

->

distinguishedName

Text

The distinguished name of the directory tree entry.

user=tswenson, o=dogboy, c=US

<-

result

Text

BER encoded content of DeleteRequest message

 

Example:

$tText := LDAP_DeleteRequest($tDN)
If ($tText = "")  `could check result code also...
  ALERT("Couldn't create Delete request!")
End If


LDAP_ModifyRequest

Syntax:

result := LDAP_ModifyRequest (distinguishedName;T ; pAttributeTypes:P ; pAttributeValues:P ; pOperation{optional}:I)

Description:

Create a modify request.

Warning:

Only single attribute values are supported - no 2D arrays!
Requires multi value attribute values (2D array) in v20 or greater.

Note:

The arrays must be of the same dimension.

Params:

In/Out

Parameter

Type

   

Example or note

->

distinguishedName

Text

The distinguished name of the entry to be changed.

user=tswenson, o=dogboy, c=US

->

pAttributeTypes

Pointer

pointer to a text array of attribute types

 

->

pAttributeValues

Pointer

pointer to a 2D text array of attribute values

2D arrays are supported in v20 or greater.

->

pOperation

Pointer

Array of longint indicating desired action per attribute. Choices are:
add - 0
delete - 1
replace - 2

If the optional iOperation parm is not passed the default operation is 'replace'

<-

result

Longint

BER encoded content of ModifyRequest message

 

Example:

$tText := LDAP_ModifyRequest($tDN;->aT_LocalAttribs;->aT_LocalValues)
If ($tText = "")  `could check result code also...
  ALERT("Couldn't create Modify request!")
End If


LDAP_ModifyRDNRequest

Syntax:

result := LDAP_ModifyRDNRequest (distinguishedName;T ; newRDN:T {; deleteOldRDN:B} )

Description:

Create a modify relative distinguished name message.

Warning:

Only single attribute values are supported.

Note:

Use of this message is dependent upon the schema of the target LDAP server.

Params:

In/Out

Parameter

Type

   

Example or note

->

distinguished name

Text

The distinguished name of the entry.

user=tswenson, o=dogboy, c=US

->

newRDN

Text

The new relative distinguished name for the given entry.

 

->

deleteOldRDN

Boolean

delete old entry? - equivalent to a move

optional parameter

<-

result

Longint

BER encoded content of ModifyRDNRequest message

 

Example:

$tText := LDAP_ModifyRDNRequest($tDN;$tPassword;FALSE)
If ($tText = "")  `could check result code also...
  ALERT("Couldn't create Modify RDN request!")
End If


LDAP_CompareRequest

Syntax:

result := LDAP_CompareRequest (distinguishedName;T ; pAttributeTypes:P ; pAttributeValues:P )

Description:

Create a compare message.

Warning:

only single attribute values are supported.

Note:

 

Params:

In/Out

Parameter

Type

   

Example or note

->

distinguishedName

Text

The distinguished name of the directory tree entry.

user=tswenson, o=dogboy, c=US

->

pAttributeTypes

Pointer

pointer to a text array of attribute types

 

->

pAttributeValues

Pointer

pointer to a text array of attribute values

 

<-

result

Text

BER encoded content of CompareRequest message

 

Example:

$tText := LDAP_CompareRequest($tDN;->tA_AttributeTypes;->tA_AttributeValues)
If ($tText = "")  `could check result code also...
  ALERT("Couldn't create Compare request")
End If


LDAP_SearchRequest

Syntax:

result := LDAP_SearchRequest (distinguishedName:T; scope:T; derefAliases:T; sizeLimit:T; timeLimit:T; searchFilter:T; pAttributeTypes:P; returnAttributes:B)

Description:

Create a search request message.

Warning:

Limitations of search filters are; doesn't handle extensibleMatch until v20 or higher.

Note:

The response to the search request can be examined using the Response Handling methods ot LDAP4D

Params:

In/Out

Parameter

Type

   

Example or note

->

distinguishedName

Text

The base object of the search

user=tswenson, o=dogboy, c=US

->

scope

Text

How to locate the base object.

Allowed values are "baseObject", "singleLevel", or "wholeSubTree"; default is "wholeSubTree"

->

derefAliases

Text

Follow aliases through the directory tree?

Allowed values are "neverDerefAliases", "derefInSearching", or "derefFindingBaseObj"; default is "neverDerefAliases"

->

sizeLimit

longint

Max number of entries the server is to return.

50

->

timeLimit

longint

per RFC 2251 sec 4.5.1: A timelimit that restricts the maximum time (in seconds) allowed for a search. A value of 0 in this field indicates that no
client-requested timelimit restrictions are in effect for the search.

30

->

searchFilter

Text

LDAP search filter - per RFC 2254 (extensible hashing in LDAP4D 2.0+)

(&(sn=swenson)(cn=*tom*)) - this means "search for all entries with attributes of last name equals "swenson" AND first name contains "tom". The asterisks "*"s are wildcard characters.

->

pAttributeTypes

Pointer

Pointer to array of attribute types

A pointer to a text array of attribute names. If the array has no elements, then server will return values of all attributes for all directory tree entries found. The attributes returned will populate the arrays that can be accessed via the

->

returnAttributes

Boolean

tell LDAP server to return attribute values?

This, of course, overrides the array values passed in pAttributetypes

<-

result

Text

BER encoded content of SearchRequest message.

 

Example:

$tText := LDAP_SearchRequest($tDN;"wholeSubTree";"neverDerefAliases";$iSizeLimit
                                       ;$iTimeLimit;$tSearchFilter;->tA_SearchAttributes;False)
If ($tText = "")  `could check result code also...
  ALERT("Couldn't create Search request!")
End If


LDAP_AddControl

Syntax:

result := LDAP_AddControl (pOIDs:P; pCriticalities:P; pControlValues:P; pMessage:P)

Description:

Add a control to an existing LDAP Message that has been created but not yet wrapped in LDAP Message envelope for sending. Since multiple controls can be sent with a single LDAP Message, the paradigm chosen for this API is to pre-assemble the data needed for the controls into arrays and have them constructed into valid BER and added to an existing message using this single command.

Warning:

No checking is done on the passed LDAP message, the conrols are merely added onto the end of the message.
The arrays to which pointers are passed must be the same size. If not, the message "LDAP_AddControl : arrays passed as parms don't have same size" will be placed into the LDAD Result error message.

Note:

$tText:=LDAP_Add Control($pOIDs;$pCriticalities;$pControlvalues;$pMessage)

Params:

In/Out

Parameter

Type

   

Example or note

->

pOIDs

pointer

Pointer to text (or string) array of OIDs (object identifiers)

From RFC 2251 sec 4.1.12: The controlType field MUST be a UTF-8 encoded dotted-decimal representation of an OBJECT IDENTIFIER which uniquely identifies the control. This prevents conflicts between control names.

->

pCriticalities

pointer

Pointer to Boolean array of criticalities

If the server does not recognize the control type and the criticality
field is TRUE, the server MUST NOT perform the operation, and MUST instead return the resultCode unsupportedCriticalExtension.

->

pControlValues

pointer

Pointer to text (or string) array of control values.

Since a control values is OPTIONAL in the RFC (but not in this API), a blank array value will be interpreted as

->

pMessage

pointer

Pointer to text of message created with and LDAP protocol message (LDAP_SearchRequest, etc.)).

 

<-

result

ongint

Success (0) or failure (-1) .

 

Example:

$result := LDAP_AddControl($pOIDs;$pCriticalities;$pControlValues;$pMessage)
If ($result # 0) 
  ALERT("Couldn't Add Control to message")
End If

Back to top