Summary: Isode provides a number of APIs which allow integrators and product developers to build components that allow client programs to connect to, query and modify data in the directory.

Functions

DS_Status DS_LDIF_Open (const char *in_fnam, const char *out_fnam, DS_LDIF **ldif_p)
 Open an LDIF stream handle with input and/or output LDIF files. More...
 
DS_Status DS_LDIF_Close (DS_LDIF *ldif)
 Close the input/output LDIF files and release all associated resources. More...
 
DS_Status DS_LDIF_Get (DS_LDIF *ldif, DS_Entry **entry_p)
 Get the next entry from the input LDIF file. More...
 
DS_Status DS_LDIF_GetDN (DS_LDIF *ldif, DS_DN **dn_p)
 Get the DN of the next entry from the input LDIF file. More...
 
DS_Status DS_LDIF_GetPut (DS_LDIF *ldif1, DS_LDIF *ldif2)
 Copy an entry across from one LDIF file to another. More...
 
DS_Status DS_LDIF_Put (DS_LDIF *ldif, const DS_Entry *entry)
 Write an entry to the output LDIF file. More...
 
DS_Status DS_LDIF_TellOutput (DS_LDIF *ldif, off_t *offset_p)
 Return the current write-offset in the output file. More...
 
DS_Status DS_LDIF_Tell (DS_LDIF *ldif, off_t *offset_p)
 Return the current read-offset in the input file. More...
 
DS_Status DS_LDIF_Seek (DS_LDIF *ldif, off_t offset)
 Seek the input file to the given file-offset. More...
 
DS_Status DS_LDIF_ErrorString (DS_LDIF *ldif, char **errstr_p)
 Return a plain-text report of all errors encountered. More...
 
DS_Status DS_LDIF_PutComment (DS_LDIF *ldif, const char *str)
 Write a comment to the output LDIF file. More...
 
DS_Status DS_LDIF_Entry2LDIFString (const DS_Entry *entry, char **str_p)
 Convert an entry to an LDIF-encoded record in memory. More...
 
DS_Status DS_LDIF_LDIFString2Entry (const char **str_p, DS_Entry **entry_p, int allow_unknown)
 Convert an LDIF-encoded record in memory into a DS_Entry. More...
 
DS_Status DS_LDIF_AllowUnknownAttrs (DS_LDIF *ldif, int allow_unknown)
 Turn on or off the flag that allows unknown attributes to be read. More...
 
DS_Status DS_LDIF_GetAllowUnknownAttrs (DS_LDIF *ldif, int *allow_unknown_p)
 Get the state of the flag that allows unknown attributes to be read. More...
 

Detailed Description

Function Documentation

◆ DS_LDIF_Open()

DS_Status DS_LDIF_Open ( const char *  in_fnam,
const char *  out_fnam,
DS_LDIF **  ldif_p 
)

Open an LDIF stream handle with input and/or output LDIF files.

Parameters
[in]in_fnamName of file to read as input, or NULL for no input
[in]out_fnamName of file to write as output, or NULL for no output
[out]ldif_pReturned handle to be used in other DS_LDIF_* calls, or NULL on error
Return values
DS_E_NOMEMORYOut of memory
DS_E_OPFAILEDIf either the input or output file could not be opened
DS_E_BADPARAMIf both in_fnam and out_fnam parameters are NULL, or if ldif_p is NULL
DS_E_NOERRORA valid handle was returned
Since
DSAPI_VERSION 2004

It is possible to set up a single DS_LDIF handle with both input and output files, or with just one or the other. Output files are always recreated blank – there is no append mode.

If the input filename has the same string value as the output filename, then a blank file is created for writing, and the input stream is also attached to the new file, allowing it to read back entries already written to the output stream. Note that the seek position is moved to the end of the file every time a new entry is added with DS_LDIF_Put(), so normally DS_LDIF_Seek() would be called before calling DS_LDIF_Get() one or more times, using file-offsets previously obtained with DS_LDIF_TellOutput().

◆ DS_LDIF_Close()

DS_Status DS_LDIF_Close ( DS_LDIF ldif)

Close the input/output LDIF files and release all associated resources.

Parameters
[in]ldifLDIF stream handle
Return values
DS_E_NOERRORResources were released without problem
Since
DSAPI_VERSION 2004

◆ DS_LDIF_Get()

DS_Status DS_LDIF_Get ( DS_LDIF ldif,
DS_Entry **  entry_p 
)

Get the next entry from the input LDIF file.

Parameters
[in]ldifLDIF stream handle
[out]entry_pNewly-read entry, or NULL on error or EOF
Return values
DS_E_NOMEMORYOut of memory
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_OPFAILEDThe stream was not opened for reading
DS_E_BADDNThe DN could not be converted
DS_E_BADENTRYBadly-formed data was found in the LDIF file
DS_E_BADATTRTYPEAn attribute could not be converted
DS_E_BADATTRVALUEAn attribute could not be converted
DS_E_BADATTRSYNTAXAn attribute could not be converted
DS_E_NOTFOUNDEnd-of-file was reached
DS_E_NOERRORAn entry was read without problem
Since
DSAPI_VERSION 2004

The caller must release the returned entry using DS_Entry_Delete(), and check its type using DS_Entry_IsNormal() and so on before using the data. If DS_E_BADENTRY is returned, then the next call will attempt to pick up after the damage or bad data. Fatal errors reading the input stream will result in a return of DS_E_BADENTRY followed by a return of DS_E_NOTFOUND on the following call.

◆ DS_LDIF_GetDN()

DS_Status DS_LDIF_GetDN ( DS_LDIF ldif,
DS_DN **  dn_p 
)

Get the DN of the next entry from the input LDIF file.

Parameters
[in]ldifLDIF stream handle
[out]dn_pNewly-read DN, or NULL on error or EOF
Return values
DS_E_NOMEMORYOut of memory
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_OPFAILEDThe stream was not opened for reading
DS_E_BADDNThe DN could not be converted
DS_E_BADENTRYBadly-formed data was found in the LDIF file
DS_E_NOTFOUNDEnd-of-file was reached
DS_E_NOERRORAn entry was read without problem
Since
DSAPI_VERSION 2025

This call returns just the DN of the entry without converting all the attributes or checking their validity. It moves the file position onto the next entry just the same as the DS_LDIF_Get() call. The caller must release the returned DN using DS_DN_Delete(). If DS_E_BADENTRY is returned, then the next call will attempt to pick up after the damage or bad data. Fatal errors reading the input stream will result in a return of DS_E_BADENTRY followed by a return of DS_E_NOTFOUND on the following call.

◆ DS_LDIF_GetPut()

DS_Status DS_LDIF_GetPut ( DS_LDIF ldif1,
DS_LDIF ldif2 
)

Copy an entry across from one LDIF file to another.

Parameters
[in]ldif1LDIF stream handle for Get operation
[in]ldif2LDIF stream handle for Put operation
Return values
DS_E_NOMEMORYOut of memory
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_OPFAILEDThe first stream was not opened for reading or the second wasn't open for writing, or there was a problem writing the entry.
DS_E_BADENTRYBadly-formed data was found in the source LDIF file
DS_E_NOTFOUNDEnd-of-file was reached
DS_E_NOERRORAn entry was read without problem
Since
DSAPI_VERSION 2025

This call quickly copies an entry from one LDIF stream to another, similar to doing a DS_LDIF_Get() on one stream followed by a DS_LDIF_Put() on the other, but with less validity-checking and greater efficiency. The two arguments may point to the same stream or to different streams. The attributes aren't decoded/re-encoded, so the validity of the attributes' types and values is not checked. If the 'Get' part fails, then that is the status returned, as for DS_LDIF_GetDN(). If it is successful, the entry data goes on to the 'Put' operation, which may give its own failure status.

◆ DS_LDIF_Put()

DS_Status DS_LDIF_Put ( DS_LDIF ldif,
const DS_Entry entry 
)

Write an entry to the output LDIF file.

Both normal entries and the four types of change-entries are handled. However, a single LDIF stream can handle only all normal-records or all change-records, selected by the first entry read from or written to the stream. Attempting to write a record of the other type will result in DS_E_BADENTRY.

Parameters
[in]ldifLDIF stream handle
[in]entryEntry to write
Since
DSAPI_VERSION 2004
Return values
DS_E_NOMEMORYOut of memory
DS_E_OPFAILEDThere was an error writing the data to the file, or the stream was not set up for writing
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_BADENTRYThe entry could not be converted to LDIF
DS_E_BADATTRTYPEAn attribute could not be converted
DS_E_BADATTRVALUEAn attribute could not be converted
DS_E_BADATTRSYNTAXAn attribute could not be converted
DS_E_BADDNSome part of the DN could not be converted
DS_E_NOERROREntry was written without problem

◆ DS_LDIF_TellOutput()

DS_Status DS_LDIF_TellOutput ( DS_LDIF ldif,
off_t *  offset_p 
)

Return the current write-offset in the output file.

Parameters
[in]ldifLDIF stream handle
[out]offset_pCurrent write-offset
Return values
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_OPFAILEDThe stream was not opened for writing
DS_E_NOERROROffset was read without problem
Since
DSAPI_VERSION 2023

This returns the offset in the output file at which the next entry will be written. This offset may be passed to DS_LDIF_Seek() to read back the next entry in a future DS_LDIF_Get() operation. Note that the read-offset for the next DS_LDIF_Get() operation is lost by this call (it is moved to the end-of-file).

◆ DS_LDIF_Tell()

DS_Status DS_LDIF_Tell ( DS_LDIF ldif,
off_t *  offset_p 
)

Return the current read-offset in the input file.

Parameters
[in]ldifLDIF stream handle
[out]offset_pCurrent read-offset
Return values
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_OPFAILEDThe stream was not opened for reading
DS_E_NOERROROffset was read without problem
Since
DSAPI_VERSION 2004

◆ DS_LDIF_Seek()

DS_Status DS_LDIF_Seek ( DS_LDIF ldif,
off_t  offset 
)

Seek the input file to the given file-offset.

Parameters
[in]ldifLDIF stream handle
[out]offsetOffset to seek to
Return values
DS_E_OPFAILEDError seeking to the given offset, or the stream was not opened for reading
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_NOERRORSeek completed without problem
Since
DSAPI_VERSION 2004

The offset value must be a value previously returned by DS_LDIF_Tell() for this file.

◆ DS_LDIF_ErrorString()

DS_Status DS_LDIF_ErrorString ( DS_LDIF ldif,
char **  errstr_p 
)

Return a plain-text report of all errors encountered.

Parameters
[in]ldifLDIF stream handle
[out]errstr_pError string, or NULL for no new errors
Return values
DS_E_NOMEMORYOut of memory
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_NOERRORAn error string or NULL has been returned
Since
DSAPI_VERSION 2004

Returns a string containing a plain-text explanation of all the errors that have occurred during reading/writing the LDIF files since the last call to this function, or NULL if there are no new errors to report. The returned string should be free'd. The string consists of lines terminated by linefeeds.

◆ DS_LDIF_PutComment()

DS_Status DS_LDIF_PutComment ( DS_LDIF ldif,
const char *  str 
)

Write a comment to the output LDIF file.

Parameters
[in]ldifLDIF stream handle
[in]strString to write
Return values
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_NOERRORSuccess
Since
DSAPI_VERSION 2014

The string is written with "# " before, and a newline after. If there are newlines embedded in the string, then extra "# " characters are inserted to make sure that the text is correctly recognised as a comment.

◆ DS_LDIF_Entry2LDIFString()

DS_Status DS_LDIF_Entry2LDIFString ( const DS_Entry entry,
char **  str_p 
)

Convert an entry to an LDIF-encoded record in memory.

Parameters
[in]entryDS_Entry to convert
[out]str_pOutput string
Return values
DS_E_NOMEMORYOut of memory
DS_E_OPFAILEDThere was an error writing the data
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_BADENTRYThe entry could not be converted to LDIF
DS_E_BADATTRTYPEAn attribute could not be converted
DS_E_BADATTRVALUEAn attribute could not be converted
DS_E_BADATTRSYNTAXAn attribute could not be converted
DS_E_BADDNSome part of the DN could not be converted
DS_E_NOERROREntry was written without problem
Since
DSAPI_VERSION 2017

The entry is converted into LDIF format and returned in as a strdup'd string, which the caller must free.

◆ DS_LDIF_LDIFString2Entry()

DS_Status DS_LDIF_LDIFString2Entry ( const char **  str_p,
DS_Entry **  entry_p,
int  allow_unknown 
)

Convert an LDIF-encoded record in memory into a DS_Entry.

Parameters
str_p[in/out] Variable pointing to string to convert
[out]entry_pOutput DS_Entry
[in]allow_unknownAllow unknown attributes to be converted? (1 yes, 0 no)
Return values
DS_E_NOMEMORYOut of memory
DS_E_BADPARAMA NULL argument was passed to the function
DS_E_BADDNThe DN could not be converted
DS_E_BADENTRYBadly-formed data was found in the LDIF file
DS_E_BADATTRTYPEAn attribute could not be converted
DS_E_BADATTRVALUEAn attribute could not be converted
DS_E_BADATTRSYNTAXAn attribute could not be converted
DS_E_NOTFOUNDEnd-of-file was reached
DS_E_NOERRORAn entry was read without problem
Since
DSAPI_VERSION 2017

The LDIF record in the given string is converted into a DS_Entry. The string pointer is updated to point after the data read (or skipped in the case of a DS_E_BADENTRY return). The caller must release the returned entry using DS_Entry_Delete(), and check its type using DS_Entry_IsNormal() and so on before using the data.

◆ DS_LDIF_AllowUnknownAttrs()

DS_Status DS_LDIF_AllowUnknownAttrs ( DS_LDIF ldif,
int  allow_unknown 
)

Turn on or off the flag that allows unknown attributes to be read.

Parameters
[in]ldifDS_LDIF stream to modify
[in]allow_unknownAllow unknown attributes? (1 yes, 0 no)
Return values
DS_E_NOERRORSuccess
DS_E_BADPARAMIf ldif is NULL or allow_unknown is something other than 0 or 1
Since
DSAPI_VERSION 2018

By default a stream is set up to return DS_E_BADATTRTYPE if any unknown attribute-types are encountered in the LDIF file. However, if the 'allow_unknown' flag is set on the stream, then these will be returned successfully as "unknown attributes", with a syntax of 'octetstring'. Unknown attributes may be output to LDIF or sent over LDAP, but not sent over DAP.

◆ DS_LDIF_GetAllowUnknownAttrs()

DS_Status DS_LDIF_GetAllowUnknownAttrs ( DS_LDIF ldif,
int *  allow_unknown_p 
)

Get the state of the flag that allows unknown attributes to be read.

Parameters
[in]ldifDS_LDIF stream to modify
[out]allow_unknown_pVariable to place result
Return values
DS_E_NOERRORSuccess
DS_E_BADPARAMIf ldif or allow_unknown_p is NULL
Since
DSAPI_VERSION 2018

The current state of the 'allow unknown attributes' flag (1 to allow, 0 to disallow) is returned in the given variable.