3.1.4.6.3 RpcAddPortEx (Opnum 61)

  • Article

RpcAddPortEx adds a port name to the list of supported ports.<359>

 DWORD RpcAddPortEx(
   [in, string, unique] STRING_HANDLE pName,
   [in] PORT_CONTAINER* pPortContainer,
   [in] PORT_VAR_CONTAINER* pPortVarContainer,
   [in, string] wchar_t* pMonitorName
 );

pName: A parameter specified in Print Server Name Parameters (section 3.1.4.1.4).

pPortContainer: A parameter specified in PORT_CONTAINER Parameters (section 3.1.4.1.8.5). The value of the Level member in the PORT_CONTAINER that is referenced by this parameter MUST be 0x00000001 or 0xFFFFFFFF.

pPortVarContainer: A pointer to a PORT_VAR_CONTAINER (section 2.2.1.2.8) information structure that contains information about the port.

pMonitorName: A pointer to a string that specifies the monitor associated with the port. For rules governing monitor names, see section 2.2.4.8.

Return Values: This method MUST return zero (ERROR_SUCCESS) to indicate successful completion or a nonzero Windows error code to indicate failure [MS-ERREF].

Upon receiving this message, the server MUST validate parameters as follows:

  • Perform the validation steps specified in Print Server Name Parameters (section 3.1.4.1.4).

  • Perform the validation steps specified in PORT_CONTAINER Parameters (section 3.1.4.1.8.5).

  • If the value of the Level member of the PORT_CONTAINER that is referenced by the pPortContainer parameter is 0xFFFFFFFF, verify that the pPortVarContainer parameter is not NULL; if that verification fails, return ERROR_INVALID_PARAMETER [MS-ERREF].

  • Verify that the port does not already exist, and if that verification fails, return ERROR_ALREADY_EXISTS [MS-ERREF].

  • Verify that the port monitor identified by the pMonitorName parameter exists, and if that verification fails, the server MUST return ERROR_INVALID_NAME [MS-ERREF].

  • Verify that the port monitor for the port supports the AddPort monitor module method, and if that validation fails, return ERROR_INVALID_PARAMETER.

  • Additional validation MAY<360> be performed.

If parameter validation fails, the server MUST fail the operation immediately and return a nonzero error response to the client. Otherwise, the server MUST process the message and compose a response to the client as follows:

  • Create a new port that is compatible with the port monitor identified by the string that is referenced by the pMonitorName parameter; if the Level member of the PORT_CONTAINER is 0xFFFFFFFF, pass the data that is contained in the PORT_VAR_CONTAINER that is pointed to by the pPortVarContainer parameter to the port monitor.

  • Associate the new port with the port monitor identified by the string that is referenced by the pMonitorName parameter.

  • Modify the list of ports in the system to include the port created by this method.

  • If any clients have registered for notification of server object changes, a notification MUST be broadcast to them.

  • Return the status of the operation.