3.1.4.44 NetrServerAliasAdd (Opnum 54)

The NetrServerAliasAdd method attaches an alias name to an existing server name and inserts Alias objects into AliasList, through which the shared resource can be accessed either with server name or alias name. An alias is used to identify which resources are visible to an SMB client based on the server name presented in each tree connect request.

 NET_API_STATUS NetrServerAliasAdd(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in] DWORD Level,
   [in, switch_is(Level)] LPSERVER_ALIAS_INFO InfoStruct

);

ServerName: An SRVSVC_HANDLE (section 2.2.1.1) that identifies the server. The client MUST map this structure to an RPC binding handle (see [C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

Level: Specifies the information level of the data. It MUST be one of the following values.

Value	Meaning
0	The buffer is of type SERVER_ALIAS_INFO_0_CONTAINER.

InfoStruct: A pointer to the SERVER_ALIAS_INFO union that contains information about the alias. The value of the Level parameter determines the type of the contents of the InfoStruct parameter, as the preceding table shows.

Return Values: The method returns 0x00000000 (NERR_Success) to indicate success; otherwise, it returns a nonzero error code. The method can take any specific error code value, as specified in [MS-ERREF] section 2.2. The most common error codes are listed in the following table.

Return value/code	Description
0x00000000 NERR_Success	The client request succeeded.
0x00000005 ERROR_ACCESS_DENIED	Access is denied.
0x00000057 ERROR_INVALID_PARAMETER	The client request failed because the specified parameter is invalid.
0x00000008 ERROR_NOT_ENOUGH_MEMORY	Not enough storage is available to process this command.
0x00000846 NERR_DuplicateShare	The alias already exists.
0x0000007C ERROR_INVALID_LEVEL	The system call level is not correct.

In response to a NetrServerAliasAdd message, the server MUST add an alias to attach the existing server name and insert it into AliasList upon successful return, or return an error code for a failure case. Multiple alias names can be attached to the same server name.

The server name to be attached to the alias is specified in the srvai*_target member of the SERVER_ALIAS_INFO structure. If the specified target name is an empty string or does not match any Transport.ServerName in the TransportList, the server SHOULD fail the call with an ERROR_INVALID_PARAMETER error code.

The Level parameter determines the type of structure that the client has used to specify information about the new alias. The value of the Level parameter MUST be 0. If the Level parameter is not equal to 0, the server MUST fail the call and return an ERROR_INVALID_LEVEL error code.

The name of the alias to be added is specified in the srvai*_alias member of the SERVER_ALIAS_INFO structure. srvai*_alias MUST be a nonempty null-terminated UTF-16 string if srvai*_default is 0 or an empty string if srvai*_default is nonzero; otherwise, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code. If srvai*_alias is a nonempty string and it matches an existing Alias.alias in the AliasList, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code. If srvai*_alias is an empty string and srvai*_default is set, the server MUST fail the call with an implementation-specific error code if DefaultServerName is not NULL. Otherwise, DefaultServerName MUST be set to srvai*_target as specified in section 3.1.1.1.

The server MAY<171> enforce security measures to verify that the caller has the required permissions to execute this call. If the server enforces these security measures and the caller does not have the required credentials, the server SHOULD<172> fail the call.

The server MUST persist the InfoStruct and Level parameters to a persistent configuration store. If an alias with the same srvai0_alias and srvai0_target already exists in the store, the preexisting entry MUST be overwritten with this entry.