Share via

3.2.4.2.1.7 GetById (Opnum 13)

  • Article

The GetById method returns the object from the collection of Objects Being Enumerated (section 3.2.1.11) whose ID matches the specified id.

 [id(FSRM_DISPID_COLLECTION | 0x03)] HRESULT GetById(
   [in] FSRM_OBJECT_ID id,
   [out, retval] VARIANT* entry
 );

id: The ID to use for identifying the object to be returned.

entry: Pointer to a VARIANT structure. Upon successful completion, it SHOULD contain the IDispatch interface of the object from the collection of Objects Being Enumerated whose ID matches the specified id.

Return Values: The method MUST return zero on success, or a nonzero error code on failure.

Return value/code

Description

0x80045301

FSRM_E_NOT_FOUND

An object with the specified ID was not found in the collection.

0x80070057

E_INVALIDARG

This code is returned for the following reasons:

  • The entry parameter is NULL.

  • The objects in the collection of Objects Being Enumerated are not one of the following interfaces: IFsrmFileScreen, IFsrmFileScreenException, IFsrmFileScreenTemplate, IFsrmFileGroup, IFsrmQuota, IFsrmQuotaTemplate, IFsrmAction, IFsrmReportJob, IFsrmReport, IFsrmClassifcationRule, IFsrmPropertyDefinition, IFsrmPipelineModuleDefinition or IFsrmFileManagementJob.

Upon receiving this message, the server MUST validate parameters:

  • Verify that entry is not NULL.

If any validation fails, the server MUST terminate processing and return a nonzero error code.

The server MUST do one of the following:

  • Set entry to the IDispatch interface of the object whose ID matches the value of the id parameter.

  • If no object in the collection of Objects Being Enumerated has an ID that matches the specified id, the server SHOULD return FSRM_E_NOT_FOUND.

  • The server SHOULD return E_INVALIDARG if the objects in the collection of Objects Being Enumerated are not one of the following interface types: IFsrmFileScreen, IFsrmFileScreenException, IFsrmFileScreenTemplate, IFsrmFileGroup, IFsrmQuota, IFsrmQuotaTemplate, IFsrmAction, IFsrmReportJob, IFsrmReport, IFsrmClassifcationRule, IFsrmPropertyDefinition, IFsrmPipelineModuleDefinition or IFsrmFileManagementJob.