NetAccessEnum or Net32AccessEnum

The NetAccessEnum API enumerates all access permission records.

Restrictions

LAN Server and OS/2 Warp Server

This API can be called from OS/2 workstations, but DLS workstations can only issue this call to a remote LAN Server workstation. OS/2 workstations can issue this call locally only if the Peer service is started. User authority is allowed limited access to this API. Administrator authority is required for full access.

Directory and Security Server Only

A DSS server always returns NERR_InvalidAPI.

Syntax

#include <netcons.h>
#include <access.h>
 
NetAccessEnum(pszServername, pszResource,
              recursive, sLevel, buf, usBuflen,
              pusEntriesReturned, pusEntriesAvail);    /* 16 bit */
 
Net32AccessEnum(pszServername, pszResource,
              recursive, ulLevel, buf, ulBuflen,
              pulEntriesReturned, pulEntriesAvail);     /* 32 bit */

Parameters

See Common Parameter Definitions for descriptions of parameters not defined here.

recursive

(16-bit short) enables or disables recursive searching. If recursive is off (0), NetAccessEnum returns entries only for the resource named. If recursive is on (nonzero), NetAccessEnum also returns an entry for each resource that branches from pszResource and has a different profile than pszResource. (For example, when a subdirectory or file has a different access profile than its parent directory.)
sLevel or ulLevel
(16-bit short or 32-bit unsigned long) can be 0 or 1, specifying which data structure to use, as described in Resource Access Data Structures.
Return Codes

The following table lists the return codes most significant to this API. (See API Return Codes for a complete list of return codes.) ┌─────────────────────────────┬───────┬────────────────────────────────────────┐│SYMBOLICCONSTANT │VALUE│MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_Success │ 0 │ No errors were encountered. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ ERROR_ACCESS_DENIED │ 5 │ Administrator privilege is required. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ ERROR_NOT_SUPPORTED │ 50 │ This request is not supported by the │
│ │ │ network. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ ERROR_BAD_NETPATH │ 53 │ The network path cannot be found. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ ERROR_NETWORK_ACCESS_DENIED │ 65 │ Network access is denied. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ ERROR_INVALID_PARAMETER │ 87 │ At least one parameter value is not │
│ │ │ valid. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ ERROR_INVALID_LEVEL │ 124 │ The sLevel parameter is not valid. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ ERROR_MORE_DATA │ 234 │ Additional data is available, but the │
│ │ │ buffer is too small. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_NetNotStarted │ 2102 │ The redirector NETWKSTA.200 has not │
│ │ │ been started. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_RemoteOnly │ 2106 │ This operation is not supported on │
│ │ │ workstations. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_InternalError │ 2140 │ An internal error has occurred. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_BadTransactConfig │ 2141 │ The server is not configured for │
│ │ │ transactions. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_ACFNotFound │ 2219 │ The NET.ACC file is missing. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_ResourceNotFound │ 2222 │ The netname cannot be found. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_ACFNotLoaded │ 2227 │ The UAS database has not been started. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_ACFFileIOFail │ 2229 │ An error was encountered in accessing │
│ │ │ the accounts database. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_InvalidDatabase │ 2247 │ The UAS database file is damaged. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_InvalidComputer │ 2351 │ The specified computer name is not │
│ │ │ valid. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘


Other codes could be returned from the following functions:

• DosAllocSeg
  
• DosFsCtl
  
• DosGetShrSeg
  
• DosOpen
Remarks

If you call this API with the buffer length parameter equal to zero, the API returns a value for total entries available. This technique is useful if you do not know the exact buffer size required.

The NetAccessEnum API can return entries only for an application having ACCESS_PERM permissions. If the user does not have administrative privileges, NetAccessEnum does not return an ERROR_ACCESS_DENIED error code. It returns NERR_Success error code with 0 entries.

The pszResource parameter limits the entries returned by NetAccessEnum. If pszResource is not a null string, it serves as a prefix for the path name. For example, if pszResource is C:\PROG, NetAccessEnum returns access permission records for resources that begin with C:\PROG.

The pusEntriesAvail parameter indicates the number of entries available for the given pszResource and recursive parameters, not the total number of entries in the access file.

Therefore, NetAccessEnum returns information only for resources without default settings below the root directory specified in the request. This is consistent semantically with a standard LAN Server API, which returns only explicit permissions. In addition, it is highly recommended that the recursive switch always be set to FALSE.

Related Information

For information about:

• Adding an access permission record, see Access Permission - NetAccessAdd.

• Retrieving information about the permissions for a resource, see Access Permission - NetAccessGetInfo.

---

[Back: NetAccessDel or Net32AccessDel]
[Next: NetAccessGetInfo or Net32AccessGetInfo]