The purpose of Advanced Server API functions and data structures is encoded in their names. All function names and data structure names include the name of the network resource. Advanced Server API functions and data structures are organized according to the following categories of network resources:
|
Access Permissions |
Handle |
Server |
|
Alert |
Mailslot |
Service |
|
Audit Policy |
Message |
Session |
|
Connection |
Pipe |
Share |
|
Configuration |
Print Destination |
Statistics |
|
Display |
Print Job |
Trust |
|
Domain |
Print Queue |
UNIX System |
|
EventLog |
Remote Utilities |
User |
|
File |
Replication |
Workstation |
|
Group |
Security |
Advanced Server API function names have at least three parts: a keyword (Net), the name of the network resource manipulated by the function, and a verb that identifies the action performed on the network resource. For example, the API function name NetUserAdd consists of the keyword Net, the category User, and the verb Add. Functions in the User category control user accounts. Add indicates that the NetUserAdd function adds a user to the user accounts database.
Some verbs appear in many categories: Add adds an object, Del deletes an object, Enum lists all objects of a particular type, GetInfo returns information about one particular object, and SetInfo sets one or all settable parameters for a particular object.
Other verbs describe familiar operations, such as Read, Write, Open, Clear, and Close. Some verbs describe tasks that are specific to network resources, such as Purge (for a communication-device or printer queue) and Raise (for an alert).
An API function name also can contain an optional fourth part: the object of the action. For example, the API function NetGroupDelUser deletes a user from the specified group. This function differs from NetGroupDel which deletes the specified group from the user accounts database.
Some API functions have "32" appended to their names. This suffix indicates that these functions are 32-bit, RPC-based equivalents of existing down-level API functions. For example, NetUserAdd32 is a 32-bit equivalent of NetUserAdd.
These API functions differ from their down-level equivalents in that they use 32-bit data structures, are RPC-based, support additional information levels, and in enumeration API functions, may have additional "resume handle" parameters.
This section contains information about the following topics:
Including Advanced Server API Definition Files
The Advanced Server API defines a set of verbs for each category of functions. The following table lists the most common verbs.
|
Verb |
Action |
|
Add |
Adds a new instance of an object. |
|
Del |
Deletes instances of an object. |
|
Enum |
Enumerates all instances of a particular object. |
|
GetInfo |
Gets detailed information about an instance of an object. |
|
SetInfo |
Changes some of the attributes on an instance of an object. |
The less common verbs perform other tasks relating to specific resources, such as logging users on (Logon) or off (Logoff) a network session.
The five most common Advanced Server API verbs use fairly standard syntax and parameters. These operations comprise the basic set of function tasks for most categories. Each of these verbs is described in the remainder of this section.
The Add verb creates new instances of an object. Add functions generally use a form of one of the following two syntax examples:
API FUNCTION
NetExampleAdd (const char * pszServer,
short sLevel,
char * pbBuffer,
unsigned short cbBuffer
);
where
pszServer points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
sLevel specifies a data structure providing a particular level of detail of information required to complete the operation.
pbBuffer points to the data structure.
cbBuffer specifies the count in bytes (size) of the buffer referenced by pbBuffer.
NET_API_STATUS NET_API_FUNCTION
NetExampleAdd32(
LPTSTR servername OPTIONAL,
DWORD level,
LBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
where
servername points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level specifies a data structure that provides the level of detail for the information required to complete the operation.
buf points to the data structure.
parm_err optionally points to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If null, the parameter is not returned on error.
The Del verb removes instances of an object. Del functions generally use a form of the one of following two syntax examples:
API FUNCTION
NetExampleDel (const char * pszServer,
const char * pszKey
);
where
pszServer points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
pszKey determines which instance to delete; for example, DOSPrintJobDel does not take a name, but rather a job number.
NET_API_STATUS NET_API_FUNCTION
NetExampleDel32(
LPTSTR servername OPTIONAL,
IN LPTSTR key
);
where
servername points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
key determines which instance to delete.
Del functions do not require a pointer to a data structure since they do not accept or return the kind of information commonly found in data structures. However, they do require an argument that specifies the object to be deleted.
The Enum verb retrieves data structures that describe some or all instances of an object. Enum functions generally use a form of one of the following two syntax examples:
API FUNCTION
NetExampleEnum (const char *pszServer,
short sLevel,
char * pbBuffer,
unsigned short cbBuffer,
unsigned short * pcEntriesRead,
unsigned short * pcTotalAvail
);
where
pszServer points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
sLevel specifies the level of detail for the returned data.
pbBuffer points to the returned data structure(s).
cbBuffer specifies the size (in bytes) of the pbBuffer memory area.
pcEntriesRead points to an unsigned short integer that specifies how many entries were returned to pbBuffer. This value is valid only if the function returns NERR_Success or ERROR_MORE_DATA.
pcTotalAvail points to an unsigned short integer that specifies how many entries were available. This value is valid only if the function returns NERR_Success or ERROR_MORE_DATA.
If pbBuffer cannot store all returning fixed-length data, the Enum function displays the NERR_BufTooSmall return code. In this case, all data in pbBuffer is invalid, but pcTotalAvail is valid.
If pbBuffer can store all returning fixed-length data but not all available variable-length data, the Enum function displays the ERROR_MORE_DATA return code. In this case, the fixed-length data in pbBuffer is valid, with pointers to any incomplete variable-length data set to NULL.
If the value of cbBuffer is 0, the Enum function returns only a valid pcTotalAvail parameter.
NET_API_STATUS NET_API_FUNCTION
NetExampleEnum32(
LPTSTR servername OPTIONAL,
DWORD level,
OUT LPBYTE * bufptr,
DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
OUT LPDWORD resume_handle OPTIONAL
);
where
servername points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level specifies the level of detail for the returned data.
bufptr points to the address containing a pointer to the returned data structure(s). This pointer is freed using NetApiBufferFree.
prefmaxlen specifies the preferred maximum length of returned data (in 8-bit bytes).
entriesread points to a DWORD that specifies how many entries were returned in the buffer pointed to by the bufptr parameter. This value is valid only if the function returns NERR_Success or ERROR_MORE_DATA.
totalentries points to a DWORD that specifies how many entries could have been enumerated from the current resume position. This value is valid only if the function returns NERR_Success or ERROR_MORE_DATA.
resume_handle points to a DWORD which on return contains a resume handle that can be used to continue a search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored. This function can be called again to get more data if ERROR_MORE_DATA is returned on a previous call and the resume_handle parameter was specified. When a function returns NERR_Success, the search is complete and all instances of the requested object have been returned.
The GetInfo verb retrieves specific information about a single instance of an object. Many Enum functions provide you with a list of objects, whereas GetInfo functions enable you to get detailed information about a specific object on a list; however, some of the Enum functions allow you to Enum with full details. Consult each API function for specific information.
GetInfo functions generally use a form of one of the following syntax examples:
API FUNCTION
NetExampleGetInfo (const char * pszServer,
char * pszKey,
short sLevel,
char * pbBuffer,
unsigned short cbBuffer,
unsigned short * pcbTotalAvail
);
where
pszServer points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
pszKey determines the instance about which information is to be returned.
sLevel specifies the level of detail that the data structure is to return.
pbBuffer points to the returned data structure.
cbBuffer specifies the size (in bytes) of the pbBuffer memory area.
pcbTotalAvail points to an unsigned short integer that specifies how many bytes of information were available, given sufficient cbBuffer .
If pbBuffer cannot store all returning fixed-length data, GetInfo displays the NERR_BufTooSmall return code. In this case, all data in pbBuffer is invalid but pcbTotalAvail is valid.
If pbBuffer can store all returning fixed-length data but not all available variable-length data, GetInfo displays the ERROR_MORE_DATA return code. In this case, the fixed-length data in pbBuffer is valid, with pointers to any incomplete variable-length data set to NULL. If the value of cbBuffer is 0, the GetInfo function returns only a valid pcbTotalAvail parameter.
NET_API_STATUS NET_API_FUNCTION
NetExampleGetInfo32(
LPTSTR servername OPTIONAL,
LPTSTR key,
DWORD level,
OUT LPBYTE * bufptr
);
where
servername points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
key determines the instance about which information is to be returned.
level specifies the level of detail for the returned data.
bufptr points to the address containing a pointer to the returned data structure(s). This pointer is freed using NetApiBufferFree.
The SetInfo verb changes some of the information of an instance of an object. SetInfo functions generally use a form of one of the following two syntax examples:
API FUNCTION
NetExampleSetInfo (const char * pszServer,
char pszkey,
short sLevel,
char * pbBuffer,
unsigned short cbBuffer,
short sParmNum
);
where
pszServer points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
pszkey determines the instance on which the information is to be set.
sLevel specifies the level of detail that the data structure is to provide.
pbBuffer points to the data structure.
cbBuffer specifies the size (in bytes) of the pbBuffer memory area.
sParmNum determines whether an entire data structure or a single data structure component is to be set. If the value is 0, a complete data structure must be provided. All settable fields must contain the information intended to be set. Otherwise, sParmNum should be the appropriate manifest constant specified by the particular SetInfo function.
NET_API_STATUS NET_API_FUNCTION
NetExampleSetInfo32(
LPTSTR servername OPTIONAL,
LPTSTR key,
DWORD level,
LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
where
servername points to an ASCIIZ string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
key determines the instance about which information is to be set.
level specifies the level of detail for the data structure.
buf points to the data structure.
parm_err optionally points to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If null, the parameter is not returned on error.
Most API functions use one or more Advanced Server-defined data structures to provide or return information defining an object or reporting its state.
Specific C data structures are defined for each API function category.
The functions in the various API function categories provide several levels of detail, each represented by a different C structure. The more detailed structures usually Ä but not always Ä include all of the information contained in lower-level structures.
When an API function can provide or return more than one level of information, an application must pass a level parameter (such as, 0, 1, or 2) to indicate the level of detail requested. Level 0 is the least detailed (often a single component), with each subsequent level calling for more detail. Levels of successively higher numbers generally contain more information.
The related level parameter is included in the data structure name. For instance, NetShareGetInfo uses the share_info_0, share_info_1, and share_info_2 data structures for data detailed at the 0, 1, and 2 levels, respectively.
Data structures with names in lower case (such as user_info_0) are 16-bit structures; data structures with names in upper case (such as USER_INFO_0) are 32-bit structures.
Many functions, particularly the SetInfo functions, require a particular data structure specified by a particular level value. If an unacceptable level parameter is passed, the function displays the ERROR_INVALID_LEVEL return code.
In moving from LAN Manager to Advanced Server, the maximum size of several data structure elements was increased. The Advanced Server environment changes the values of these constants. For example, LAN Manager defines "NNLEN" (maximum length of a share name) to 12: Advanced Server redefines "NNLEN" to 80, but creates a new constant "LM20_NNLEN" that is defined as 12.
To maintain binary compatibility, all APIs described in this document use the LAN Manager-compatible constants rather than the redefined, larger constants. The following table summarizes the changed constants:
|
LAN Manager Constant |
NT Constant |
Description |
|
LM20_NNLEN = 12 |
NNLEN = 80 |
Maximum share name length |
|
LM20_RMLEN = 30 |
RMLEN = 98 |
Maximum remote name length |
|
LM_SNLEN =- 15 |
SNLEN = 80 |
Maximum service name length |
|
LM_STXTLEN= 63 |
STXTLEN = 256 |
Maximum service text length |
|
LM20_DEVLEN = 8 |
DEVLEN = 80 |
Maximum device name length |
|
LM20_UNLEN = 20 |
UNLEN = 256 |
Maximum user name length |
|
LM20_GNLEN = 20 |
GNLEN = 256 |
Maximum group name length |
|
LM20_PWLEN = 14 |
PWLEN = 256 |
Maximum password length |
|
LM20_MAXCOMMENTSZ= 48 |
MAXCOMMENTSZ = 256 |
Maximum comment size |
|
LM20_QNLEN = 12 |
QNLEN = 80 |
Maximum queue name length |
Note
The 32-bit, RPC-based API functions that are contained in the librpcapi.so library were added specifically for Advanced Server; they are not LAN Manager-compatible. These APIs can be executed remotely only on other Advanced Servers for UNIX Systems computers or Windows NT computers.
The NetShareGetInfo function’s three data structures illustrate the levels of detail an API function can provide. The share_info_0 data structure returns only the share name of a particular resource (NetShareEnum returns a set of these structures — a list containing the names of all resources shared on the server):
struct share_info_0(
char shi0_netname[LM20_NNLEN+1];
);
The share_info_1 data structure returns the name of the shared resource, plus parameters specifying the type of resource and an optional remark provided via the NetShareSetInfo function when the share was added on the server. (NetShareSetInfo requires a level 1 or 2 data structure.)
NetShareEnum, at level 1, returns a set of share_info_1 data structures — one for each resource shared on the server:
struct share_info_1(
char shi1_netname[LM20_NNLEN+1];
char shi1_pad1;
unsigned short shi1_type;
char * shi1_remark;
};
The share_info_2 data structure adds information on the permissions, path name, number of current uses, and password for a share to the information provided by the share_info_1 data structure:
struct share_info (
char shi2_netname[LM20_NNLEN+1];
char shi2_pad1;
unsigned short shi2_type;
char * shi2_remark;
unsigned short shi2_permissions;
unsigned short shi2_max_uses;
unsigned short shi2_current_uses;
char * shi2_path;
char shi2_passwd[SHPWLEN+1];
char shi2_pad2;
};
When a data structure that defines a pointer to variable-length data (such as an ASCIIZ string) is passed to or returned by a down-level function, the application must provide a buffer large enough to store both the fixed-length and variable-length data. Otherwise, not all of the data can be passed or returned.
If a buffer is too small to hold all variable-length data associated with a structure, the application should notify the function that no variable-length data is being passed by specifying NULL pointers to the variable-length data.
If an application calls a function that could return more variable-length data than the buffer can store, the function returns as much data as possible, setting all pointers for information that was not returned to NULL. In this case, GetInfo functions also display the ERROR_MORE_DATA return code and the number of bytes required to store all available data (the BytesAvail value); Enum functions return the total entries available (the TotalEntries value). If the buffer is too small for the fixed-length data, the function displays the NERR_BufTooSmall return code and the amount of data that can fit into the buffer to be returned.
API functions that are 32-bit, RPC-based never require the caller to allocate the buffer in which the function is to return data. This buffer is allocated internally by the API function and the pointer to it is returned to the caller.
The caller must use NetApiBufferFree on the buffer to free it after the data in it no longer are needed.
Advanced Server API functions can be executed on the local computer. Many API functions can also be executed on a remote server. Functions that can be executed remotely supply the name of an accessible remote computer as the servername parameter.
Remote execution of an API function requires that the following conditions exist:
The remote server must share IPC$, the special interprocess communications resource.
The calling program must have the proper administrative privileges (the ADMIN$ resource).
If an application tries to execute an API function on a remote server that is not sharing ADMIN$ or IPC$, the NERR_BadTransactConfig code is returned.
Each API function verifies that the user has the appropriate security requirements to execute the function. Servers perform appropriate access checks before permitting or performing operation. For more information about security, see Advanced Server Concepts and Planning. If your account does not have appropriate group memberships, contact your system administrator.
The security requirements for each API function are specified on each API manual page.
The Advanced Server API defines name formats (ASCIIZ strings) to distinguish various parts of the network software. Thus, an API function easily can distinguish which type of resource or device parameter is being passed.
The format and maximum length of each type of name are defined in the netcons.h include file.
All characters can be used in network names except ASCII characters less than 20 hexadecimals and the following special characters:
" / [ ] : | < > + = ; , \
Periods can be used; however, they cannot be the first character of a network name or immediately follow another period in a name. Thus work.sta.1 is valid, but .work.sta.1 and work..sta.1 are invalid.
The include files declare information that is required by Advanced Server API functions, such as constants, storage classes, and function parameter types. These files can be found in /usr/include/lmx.
