Scans the bindery of the specified connection and returns matching tree objects.
#include <nwnet.h>
or
#include <nwdsconn.h>
N_EXTERN_LIBRARY (NWDSCCODE) NWDSReturnBlockOfAvailableTrees (
NWDSContextHandle context,
NWCONN_HANDLE connHandle,
pnstr scanFilter,
pnstr lastBlocksString,
pnstr endBoundString,
nuint32 maxTreeNames,
ppnstr arrayOfNames,
pnuint32 numberOfTrees,
pnuint32 totalUniqueTrees);
uses netwin32
Function NWDSReturnBlockOfAvailableTrees
(context : NWDSContextHandle;
connHandle : NWCONN_HANDLE;
scanFilter : pnstr;
lastBlocksString : pnstr;
endBoundString : pnstr;
maxTreeNames : nuint32;
Var arrayOfNames : pnstr;
Var numberOfTrees : nuint32;
Var totalUniqueTrees : nuint32
) : NWDSCCODE;
(IN) Specifies the NDS context for the request or NULL for the preferred tree.
(IN) Specifies the connection handle to be used in scanning for eDirectory trees.
(IN) Points to an ASCII string that defines the scan filter (can contain wildcards).
(IN) Points to the last tree name that was returned during a previous scan (used to continue scanning for more names with the same scan filter or pass NULL).
(IN) Points to a string (used in conjunction with the scanFilter parameter) that sets up a range of tree names to scan (optional).
(IN) Specifies the maximum number of tree names to return (size of the arrayOfNames buffer).
(OUT) Points to the first element of an output buffer that will be used to return the tree names.
(OUT) Points to the actual number of tree names that were returned in the arrayOfNames parameter.
(OUT) Points to the total number of tree names found that match the scan criteria (might be greater than the numberOfTrees parameter since the buffer size controls how many names are actually returned).
These are common return values.
|
0x0000 0000 |
SUCCESSFUL |
|
NO_SUCH_OBJECT |
|
nonzero value |
Nonzero values indicate errors. See |
This function returns tree names in sorted order and with duplicates removed.
To set up a scan, place a filter string in the scanFilter parameter and set the endBoundString parameter to NULL. The filter string can contain a wildcard, such as "nov*". The results of this scan would include all tree names that begin with "nov".
If you want to set an end boundary for the scan, place a second filter string in the endBoundString parameter. For example, if the scanFilter parameter contains "a*" and endBoundString contains "ac*", the scan results would include all tree names that begin with "a" that are less than the ordinal value of "ad".
Initializing the Output Buffer. You are responsible for setting up and initializing an output buffer before calling NWDSReturnBlockOfAvailableTrees. You must supply the array of pointers as well as supplying strings of NW_MAX_TREE_NAME_LEN for each element in the array. The following example demonstrates initializing the buffer.
main()
{
ppnstr8 names;
int i;
int blockOfTreesCount = 25;
names = malloc(sizeof(pnstr8) * blockOfTreesCount);
for (i=0; i<25; i++)
{
names[i] = malloc(NW_MAX_TREE_NAME_LEN);
}
NWDSReturnBlockOfAvailableTrees(,,,,,,names,,);
}
You could set the maxTreeNames parameter equal to 0 and call NWDSReturnBlockOfAvailableTrees. The value returned in the totalUniqueTrees parameter could then be used to determine how much memory to allocate for the arrayOfNames parameter.
NOTE:NW_MAX_TREE_NAME_LEN contains the maximum length of non-Unicode names, and NW_MAX_TREE_NAME_BYTES contains the maximum length of Unicode names. The DCV_XLATE_STRINGS flag determines whether local code page format or Unicode strings are returned. For more information, see DCK_FLAGS Key.
Continuing a Scan. If the value returned in the totalUniqueTrees parameter is greater than the value returned in the numberOfTrees parameter, there are more tree names that meet the scan filter criteria than were returned in the arrayOfNames parameter. If this is the case, make a subsequent call to NWDSReturnBlockOfAvailableTrees and begin the scan where the previous call left off.
To set up a subsequent call, keep the values of the scanFilter and endBoundString parameters the same as before, and place the name that was returned in the last element of the arrayOfNames parameter into the lastBlocksString parameter.