3.1.4.17 RRPC_FWEnumConnectionSecurityRules (Opnum 16)

  • Article

The RRPC_FWEnumConnectionSecurityRules method requests the server to return all the connection security rules contained in the store that is referenced by the hPolicy handle. The method returns a linked list of all the connection security rule objects.

 ULONG RRPC_FWEnumConnectionSecurityRules(
   [in] FW_CONN_HANDLE rpcConnHandle,
   [in] FW_POLICY_STORE_HANDLE hPolicy,
   [in] ULONG dwFilteredByStatus,
   [in] ULONG dwProfileFilter,
   [in] USHORT wFlags,
   [out, ref] ULONG* pdwNumRules,
   [out] PFW_CS_RULE2_0* ppRules
 );

rpcConnHandle: This parameter is an RPC binding handle that connects to the RPC interface of the Firewall and Advanced Security Protocol.

hPolicy: This input parameter is an FW_POLICY_STORE_HANDLE data type. The data type MUST contain an opened policy store handle that is successfully opened by using the RRPC_FWOpenPolicyStore (Opnum 0) method. The handle MUST have read or read/write access rights.

dwFilteredByStatus: This parameter is a combination of flags from the FW_RULE_STATUS_CLASS enumeration. This method uses this bitmask to determine which rules will be returned. Rules that contain a status code from the class that is specified by this parameter will be returned in the linked list.

dwProfileFilter: This parameter is a combination of flags from the FW_PROFILE_TYPE enumeration. This method also uses this parameter to determine which rules will be returned. Rules that contain a profile that is specified by this parameter will be returned in the linked list.

wFlags: This parameter is a combination of flags from the FW_ENUM_RULES_FLAGS enumeration, which modifies the behavior of the method and performs operations on the rules before returning them in the linked list.

pdwNumRules: This output parameter, if successful, MUST be equal to the number of rules returned.

ppRules: This output parameter, if successful, contains a linked list of FW_CS_RULE2_0 data types.

Return Values: The method returns 0 if successful; if it fails, it returns a nonzero error code. The field can take any specific error code value, as specified in [MS-ERREF]. The following return values are common.

Return value/code

Description

0x00000005

ERROR_ACCESS_DENIED

The client does not have the required credentials to call the method.

0x00000057

ERROR_INVALID_PARAMETER

The dwProfileFilter parameter contains invalid profiles.

Exceptions Thrown: No exceptions are thrown except those that are thrown by the underlying RPC protocol, as specified in [MS-RPCE]. If any lower-layer errors are reported by RPC exception, this exception is converted to an error code and reported to higher-layer protocols via the return value.

The server MUST validate that the client is authorized to perform the requested operation (as defined in section 3.1.4) before executing this method.