NWIntScanForTrusteesExt

Syntax

   #include <nwdentry.h> 
   or 
   #include <nwcalls.h> 
    
   N_EXTERN_LIBRARY(NWCCODE) NWIntScanForTrusteesExt ( 
      NWCONN_HANDLE           conn,  
      NWDIR_HANDLE            dirHandle,  
      const nstr8 N_FAR      *path,  
      pnuint32                iterHandle,  
      pnuint16                numOfEntries,  
      NWET_INFO_EXT N_FAR    *entryTrusteeInfo,  
      nuint16                 augmentFlag);
   

Parameters

conn

(IN) Specifies the NetWare server connection handle.

dirHandle

(IN) Specifies the NetWare directory handle pointing to the directory or file to scan.

path

(IN) Points to an absolute directory or file path (if the dirHandle parameter is 0) or one relative to the dirHandle parameter. An absolute path must not be more than 255 bytes long. The characters in the string must be UTF-8.

iterHandle

(IN/OUT) Points to the server maintained sequence number (set to 0 initially).

numOfEntries

(OUT) Points to the buffer to receive the number of entries returned by NWIntScanForTrusteesExt.

entryTrusteeInfo

(OUT) Points to the NWNET_INFO_EXT structure.

augmentFlag

(IN) Specifies if wildcards are augmented:

• 0 = wildcards are not augmented
• nonzero = wildcards are augmented

Return Values

These are common return values; see Return Values (Return Values for C) for more information.

Remarks

NWIntScanForTrusteesExt works for both files and directories on NSS volumes.

Directories can have any number of objects as trustees. Trustees are returned in groups of 100 TRUSTEE_INFO structures. To obtain a complete list, set the iterHandle parameter to 0 for the initial call. NWIntScanForTrusteesExt should then be called (for example in a while or do loop) until it returns 0x899C (NO_MORE_TRUSTEES). Because 0x899C also indicates INVALID_PATH, ensure the dirHandle/path parameter combination is correct.

Due to subtle differences in operation, trustees may remain after an iteration, even though not all 100 positions are filled. If a position is not filled, the objectID parameter is set to 0L. Check the objectID parameter before printing each value in the objectRights parameter.

Both the dirHandle and path parameters must be in the default name space.

The default name space is the name space that matches the OS and the loaded name spaces on that volume. For example, Windows 95 on a volume with LONG name space will set LONG name space as the default name space.

The dirHandle parameter can be zero if the path parameter points to the complete path, including the volume name. The path parameter can point to wildcard characters. However, only the first matching directory is scanned.

The NWET_INFO_EXT structure receives trustee information. The sequenceNumber field should always be ignored.

NCP Calls

• 0x2222 22 12 Scan Directory For Trustees
• 0x2222 22 38 Scan File Or Directory For Extended Trustees
• 0x2222 23 17 Get File Server Information
• 0x2222 87 05 Scan File Or Subdirectory For Trustees
• 0x2222 89 05 Scan File Or Subdirectory For Trustees

Example

The following snippet of code shows how to use a do/while loop to repeatedly scan the trustee list for multiple entries. Before displaying the list to a user, the objectID and objectRights need to be mapped to something easier to read.

   void PrintTrustees (NWCONN_HANDLE conn, const char *path)
   {
      nuint32 iterHandle;
      nuint16 numOfEntries;
      NWET_INFO_EXT trusteeInfo;
      NWCCODE ccode;
      int index;
   
   
      printf("Trustees for %s:\n", path);
      iterHandle = 0;
      do
      {
         ccode = NWIntScanForTrusteesExt(conn, 0, path, &iterHandle,
                 &numOfEntries, &trusteeInfo, 0);
         if (ccode == NO_MORE_TRUSTEES)
         break;
   
         if (ccode == 0)
         {
             for (index = 0; index < 100; index++)
             {
                if (trusteeInfo.trusteeList[index].objectID != 0)
                {
                    printf("  0x%08X: 0x%04X\n",
                            trusteeInfo.trusteeList[index].objectID,
                             trusteeInfo.trusteeList[index].objectRights);
                }
             }
         }   } while (ccode != 0);}