Share via

3.1.4.23 NetrServerTransportAddEx (Opnum 41)

  • Article

The NetrServerTransportAddEx method binds the specified server to the transport protocol. This extended method allows the caller to specify information levels 1, 2, and 3 beyond what the NetrServerTransportAdd method allows.

 NET_API_STATUS NetrServerTransportAddEx(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in] DWORD Level,
   [in, switch_is(Level)] LPTRANSPORT_INFO Buffer
 );

ServerName: An SRVSVC_HANDLE (section 2.2.1.1) pointer 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. This parameter MUST be the following value.

Value

Meaning

0

The buffer is of type SERVER_TRANSPORT_INFO_0.

1

The buffer is of type SERVER_TRANSPORT_INFO_1.

2

The buffer is of type SERVER_TRANSPORT_INFO_2.

3

The buffer is of type SERVER_TRANSPORT_INFO_3.

Buffer: A pointer to the TRANSPORT_INFO union that describes the data. The type of data depends on the value of the Level 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.

0x00000034

ERROR_DUP_NAME

A duplicate name exists on the network.

0x0000007C

ERROR_INVALID_LEVEL

The system call level is not correct.

0x00000057

ERROR_INVALID_PARAMETER

The parameter is incorrect.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

The server SHOULD<94> enforce security measures to verify that the caller has the required permissions to execute this call. If the caller does not have the required credentials, the server SHOULD<95> fail the call.

The Level parameter determines the type of structure that the client has used to specify information about the new transport. The value MUST be 0, 1, 2, or 3. If the Level parameter is not equal to one of the valid values, the server MUST fail the call with an ERROR_INVALID_LEVEL error code.

If the Level parameter is 0, the Buffer parameter points to a SERVER_TRANSPORT_INFO_0 structure.

If the Level parameter is 1, the Buffer parameter points to a SERVER_TRANSPORT_INFO_1 structure.

If the Level parameter is 2, the Buffer parameter points to a SERVER_TRANSPORT_INFO_2 structure.

If the Level parameter is 3, the Buffer parameter points to a SERVER_TRANSPORT_INFO_3 structure.

The server MUST validate all information that is provided in the SERVER_TRANSPORT_INFO structure and MUST fail the call with ERROR_INVALID_PARAMETER if any of these checks fail:

  • Both svti*_transportname and svti*_transportaddress MUST NOT be NULL; svti*_transportaddresslength MUST NOT be zero.

  • If svti*_domain is not NULL, its length MUST NOT be greater than 15.

  • The svti*_flags can be any combination of the following flags as defined in section 2.2.4.96: 0, SVTI2_REMAP_PIPE_NAMES, and SVTI2_SCOPED_NAME.

The server MUST invoke the events specified in [MS-CIFS] section 3.3.4.17 and [MS-SMB2] section 3.3.4.21, passing the following as the parameters: svti*_transportname, svti*_transportaddress, and a transport enable flag set to TRUE.

If both the CIFS and SMB2 servers return ERROR_NOT_SUPPORTED, the server MUST return ERROR_NOT_SUPPORTED (0x00000032) to the caller. If both the CIFS and SMB2 servers return an error other than ERROR_NOT_SUPPORTED, the server must fail the call with an implementation-dependent error.

If either the CIFS or SMB2 server returns STATUS_SUCCESS, the server MUST create a new Transport and add it to the TransportList. The Transport MUST be initialized as follows:

  • Transport.Name MUST be set to the caller-supplied svti*_transportname. For acceptable forms of svti*_transportname, see section 2.2.4.96.

  • Transport.ServerName MUST be set to the caller-supplied svti*_transportaddress. For acceptable forms of svti*_transportaddress, see section 2.2.4.96.

  • Transport.Domain MUST be set to svti*_domain.

  • Transport.Flags MUST be set to svti*_flags.

  • Transport.ConnectionCount MUST be set to zero.

  • The Transport MUST be persisted in an implementation-specific store.

The server MUST then return NERR_Success to the caller.