IRPCSearch.GetFolderContentsOrDelta
Vault API / core read session or assertion idempotent returns metadata structure version
Gets the contents of the specified folder, or a delta that indicates changes to document vault data since the logical timestamp known by the caller.
| Service | Search MFiles.IRPCSearch |
|---|---|
| gRPC method | /MFiles.IRPCSearch/GetFolderContentsOrDelta |
| HTTP (mf-http-grpc) | POST /grpc/v1/get-folder-contents-or-delta |
| Request | GetFolderContentsOrDeltaRequest |
| Response | GetFolderContentsOrDeltaResponse |
| Book and level | Vault API, core |
| Kind | read |
| Session | Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata). |
| Idempotent | yes |
| Returns metadata structure version | yes (in the mfiles-metadata-version-bin trailer) |
| Streaming | none (unary) |
Remarks
Used by the M-Files clients to refresh a cached folder listing. For a plain listing, use GetFolderContents.
Request: GetFolderContentsOrDeltaRequest
Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
callimp | CallImportance | The importance level of this call. Typically CALL_IMPORTANCE_NORMAL.Values: CALL_IMPORTANCE_DEFAULT (0), CALL_IMPORTANCE_NORMAL (1), CALL_IMPORTANCE_CAN_BE_REJECTED (2). |
search_options | SearchTarget | Search options. |
search_options.index | string | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
search_options.mode | SearchMode | Whether to prefer, require or avoid the full-text search engine. See SearchMode.Values: SEARCH_MODE_DEFAULT (0), SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH (1), SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH (2), SEARCH_MODE_REQUIRE_DATABASE_SEARCH (3). |
search_options.search_master_storage | bool | True to also search objects kept in Master Storage, where the vault supports it. |
search_options.continuation_token | string | Continuation token for paging results from Master Storage. SearchObjects does not support it and fails with "Continuation token is not supported." when it is set together with search_master_storage. |
parent[] | repeated Folder | Describes the parent folder. |
parent[].type | FolderType | The type of the folder, for example FOLDER_TYPE_VIEW_FOLDER or FOLDER_TYPE_PROPERTY_FOLDER.Values: FOLDER_TYPE_UNKNOWN (0), FOLDER_TYPE_ANY_FOLDER (1), FOLDER_TYPE_VIEW_FOLDER (2), FOLDER_TYPE_PROPERTY_FOLDER (3), FOLDER_TYPE_TRADITIONAL_FOLDER (4), FOLDER_TYPE_SEARCH_FOLDER (5), FOLDER_TYPE_EXTERNAL_VIEW_FOLDER (6). |
parent[].data | FolderInfoUnion | Additional folder type -specific information as a union. |
parent[].data.any_folder | FolderInfoUnion.AnyFolderData (oneof data) | Any folder type. |
parent[].data.view_folder | FolderInfoUnion.ViewFolderData (oneof data) | View folder type. |
parent[].data.property_folder | FolderInfoUnion.PropertyFolderData (oneof data) | Property (virtual) folder type. |
parent[].data.traditional_folder | FolderInfoUnion.TraditionalFolderData (oneof data) | Traditional folder type. |
parent[].data.search_folder | FolderInfoUnion.SearchFolderData (oneof data) | Search folder (extended view folder) type. |
parent[].data.external_view_folder | FolderInfoUnion.ExternalViewFolderData (oneof data) | External view folder type. |
results_page_requests[] | repeated SearchResultsPageRequest | If not empty, specifies search results page requests. |
results_page_requests[].object_type | int32 | The identifier of a search results group. |
results_page_requests[].page | int32 | The zero-based index of a page. |
results_page_requests[].options | SRPREQUESTFLAGS | Search results page request flags. |
results_page_requests[].options.all | bool | Specifies all flags set; Including any future flags. |
results_page_requests[].options.unseen_page | bool | If available, the page request is for an unseen page. |
results_page_requests[].options.ignore_original_conditions | bool | If available, the original conditions are ignored. This can be used when including ObjIDs. Do not use with SRPREQUEST_UNSEENPAGE. |
results_page_requests[].options.seen_page | bool | If available, the page request is for an already seen page. |
results_page_requests[].options.initial_page | bool | If available, the page request is initial and for an unseen page. Do not use with SRPREQUEST_SEENPAGE. |
results_page_requests[].seen_objects[] | repeated ObjID | An array of ObjIDs. If the SRPREQUEST_UNSEENPAGE flag is available, these are ObjIDs to exclude. If the SRPREQUEST_SEENPAGE flag is available, these are ObjIDs to include. |
results_page_requests[].seen_objects[].type | int32 | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
results_page_requests[].seen_objects[].item_id | ItemID | The ID of the object within its type, in item_id.internal_id. |
callers_current_vcversion | int64 | The vault content version ID currently known by the caller. If the vault content has not been updated since, *pi64CurrentVCVersionOnServer is set to this same number and no data is returned. Specify zero to force the retrieval of normal folder contents. When this is zero, the server never returns an appropriate delta. |
allow_returning_delta | bool | True if the caller allows returning a delta (changes to the vault content). |
upper_change_limit_for_delta | uint32 | Specifies an upper change limit for returning a delta. If changes are no more than this limit, a delta can be returned. |
max_results | uint32 | Requested max results. If this is 0, it should be ignored. |
facet_filter | StringValue | If set, specifies the additional facet search filter. |
facet_filter.value | string | String. |
sorting | SearchResultsSorting | If not empty, specifies how search results are being sorted. |
sorting.rules | SortRuleValueArray | The sort rule. Exactly one rule is supported; more than one cannot be sorted. |
sorting.rules.values[] | repeated SortRule | Sort rules. The first rule has the highest presedence meaning that it is the primary sort rule. |
sorting.options | SortFlags | Sort flags. Set allow_resorting_to_default_sort to get relevance order instead of an error when the rule cannot be applied. |
sorting.options.all | bool | Specifies all flags set; Including any future flags. |
sorting.options.allow_resorting_to_default_sort | bool | Allows resorting to default sorting if the specified sorting is not supported. If this flag is not present, an unsupported sort request causes an error. |
Response: GetFolderContentsOrDeltaResponse
Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.
| Field | Type | Description |
|---|---|---|
current_vcversion_on_server | int64 | Receives the current vault content version on the server. If this is the same as the one specified by the caller, no delta data is returned. However a full folder content can be returned to refresh the single folder. |
views_or_delta | ViewsOrDelta | Views or delta. |
views_or_delta.type | bool | True if this struct represents a delta (i.e. just the occurred changes to views). |
views_or_delta.removed_views[] | repeated int32 | Removed views. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
views_or_delta.views[] | repeated View | Views. This contains inserted or updated views if this struct represents a delta, otherwise it contains just a "normal" array of views. |
views_or_delta.views[].id | int32 | The ID of the view. |
views_or_delta.views[].type | ViewType | The type of the view.Values: VIEW_TYPE_SHOW_OBJECTS (0), VIEW_TYPE_FILTER_ONLY (1). |
views_or_delta.views[].name | string | The name of the view. |
views_or_delta.views[].is_common | bool | Tells if the view is admin-defined (common) or user-defined. |
views_or_delta.views[].is_visible | bool | Tells if the view is visible. |
views_or_delta.views[].location | ViewLocation | The location of the view. Valid only if bHasParent is true. |
views_or_delta.views[].content_definition | SearchDef | The search definition that contains the view levels and search conditions of the view. |
views_or_delta.views[].acl | AccessControlList | Permissions. |
views_or_delta.views[].flags_obsolete | uint32 | Bit flags that provide additional information on the view. |
views_or_delta.views[].options | VIEWFLAGS | Bit flags that provide additional information on the view. |
views_or_delta.views[].guid | string | GUID for the view. |
views_or_delta.views[].view_visualization | ViewVisualization | View visualization information. |
property_folders_or_delta | PropertyFoldersOrDelta | Property folders or delta. |
property_folders_or_delta.type | bool | True if this struct represents a delta (i.e. just the occurred changes to property folders). |
property_folders_or_delta.removed_folders[] | repeated TypedValue | Removed property folders. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
property_folders_or_delta.removed_folders[].is_null_value | bool | True if the value is empty. data is then unset. |
property_folders_or_delta.removed_folders[].type | Datatype | The data type of the value. |
property_folders_or_delta.removed_folders[].data | TypedValueUnion | The value, in the member that matches type. Unset for an empty value. |
property_folders_or_delta.folders[] | repeated TypedValue | Property folders. This contains inserted or updated property folders if this struct represents a delta, otherwise it contains just a "normal" array of property folders. |
property_folders_or_delta.folders[].is_null_value | bool | True if the value is empty. data is then unset. |
property_folders_or_delta.folders[].type | Datatype | The data type of the value. |
property_folders_or_delta.folders[].data | TypedValueUnion | The value, in the member that matches type. Unset for an empty value. |
traditional_folders_or_delta | TraditionalFoldersOrDelta | Traditional folders or delta. |
traditional_folders_or_delta.type | bool | True if this struct represents a delta (i.e. just the occurred changes to traditional folders). |
traditional_folders_or_delta.removed_folders[] | repeated int32 | Removed traditional folders. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
traditional_folders_or_delta.folders[] | repeated Lookup | Traditional folders. This contains inserted or updated traditional folders if this struct represents a delta, otherwise it contains just a "normal" array of traditional folders. |
traditional_folders_or_delta.folders[].value_list_item_info | ItemInfo | The selected item. Only obj_id is needed when setting a value. |
traditional_folders_or_delta.folders[].version | ObjVerVersion | The version of the selected object. The server returns OBJ_VER_VERSION_TYPE_LATEST (-1), meaning the latest version. |
objects_or_delta | ObjectsOrDelta | Objects or delta. |
objects_or_delta.type | bool | True if this struct represents a delta (i.e. just the occurred changes to objects). |
objects_or_delta.removed_objects[] | repeated ObjID | Removed objects. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
objects_or_delta.removed_objects[].type | int32 | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
objects_or_delta.removed_objects[].item_id | ItemID | The ID of the object within its type, in item_id.internal_id. |
objects_or_delta.objects[] | repeated SearchResultsItem | Objects. This contains inserted or updated objects if this struct represents a delta, otherwise it contains just a "normal" array of objects. |
objects_or_delta.objects[].object | ObjectVersionEx | The object and the found version: object ID, version, title, class, files and status. Property values are not included. |
objects_or_delta.objects[].score | int32 | The relevance score of the result. Higher is more relevant. |
objects_or_delta.objects[].chunk | string | For an Aino search, the passage of text that matched. Empty for other searches. |
objects_or_delta.object_property_values[] | repeated PropertyValueArray | Objects' property values. |
objects_or_delta.object_property_values[].value[] | repeated PropertyValue | Property values. |
objects_or_delta.object_acls[] | repeated AccessControlList | If not empty, objects' ACLs. |
objects_or_delta.object_acls[].checked_out_to_user | int32 | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
objects_or_delta.object_acls[].is_fully_authoritative | bool | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
objects_or_delta.object_acls[].custom_component | AccessControlListComponent | Accesses the custom component of this ACL. |
objects_or_delta.object_acls[].restrictive_components[] | repeated AccessControlListComponentMapEntry | Accesses the restrictive automatic components of this ACL. |
objects_or_delta.object_acls[].secondary_access_control_list | AccessControlList (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
objects_or_delta.object_acls[].additive_components[] | repeated AccessControlListComponentMapEntry | Accesses the additive automatic components of this ACL. |
objects_or_delta.limited_item_groups[] | repeated int32 | Receives the list of item group identifications ids those results were limited. The group identification id depends on how the search results were grouped. E.g. object type id. |
objects_or_delta.continuation_token | string | Continuation token for paginating search results from Master Storage. |
objects_or_delta.has_additional_results | bool | True if there are additional results that can't be counted in advance. |
vl_items_delta | ValueListItemsDelta | Value list items delta. Valid only if a delta is returned for objects. |
vl_items_delta.changed_value_lists[] | repeated int32 | Changed value lists. |
json_external_view_folders_or_delta[] | repeated ExternalView | External views or delta. |
json_external_view_folders_or_delta[].id | ExternalRepositoryID | The view ID in external repository. |
json_external_view_folders_or_delta[].id.connection | string | The external repository connection identifier. |
json_external_view_folders_or_delta[].id.item | string | External ID within the scope of the connection to external system. |
json_external_view_folders_or_delta[].display_name | string | The name of the view. |
json_external_view_folders_or_delta[].external_repository_icon_id | string | The icon ID. |
json_external_view_folders_or_delta[].parent_id | ExternalRepositoryID | The view's parent ID in external repository. May be uninitialized if the external view does not have a parent. |
json_external_view_folders_or_delta[].parent_id.connection | string | The external repository connection identifier. |
json_external_view_folders_or_delta[].parent_id.item | string | External ID within the scope of the connection to external system. |
json_external_view_folders_or_delta[].object_data | ObjectVersionExWP | If not null, the object representation of the folder. |
json_external_view_folders_or_delta[].object_data.object_version | ObjectVersionEx | Object info. |
json_external_view_folders_or_delta[].object_data.properties[] | repeated PropertyValue | Property values, or an empty array. |
json_external_view_folders_or_delta[].object_data.acl | AccessControlList | If set, ACL. |
json_external_view_folders_or_delta[].object_data.current_user_permissions | ObjectPermissionsForClient | If set, permissions of the object version. |
json_external_view_folders_or_delta[].folder_capabilities | FOLDERCAPABILITYFLAGS | Bit flags that provide information on the folder capabilities. |
json_external_view_folders_or_delta[].folder_capabilities.all | bool | Specifies all flags set; Including any future flags. |
json_external_view_folders_or_delta[].folder_capabilities.can_search_within_this_folder | bool | |
json_external_view_folders_or_delta[].acl | AccessControlList | If set, ACL. |
json_external_view_folders_or_delta[].acl.checked_out_to_user | int32 | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
json_external_view_folders_or_delta[].acl.is_fully_authoritative | bool | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
json_external_view_folders_or_delta[].acl.custom_component | AccessControlListComponent | Accesses the custom component of this ACL. |
json_external_view_folders_or_delta[].acl.restrictive_components[] | repeated AccessControlListComponentMapEntry | Accesses the restrictive automatic components of this ACL. |
json_external_view_folders_or_delta[].acl.secondary_access_control_list | AccessControlList (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
json_external_view_folders_or_delta[].acl.additive_components[] | repeated AccessControlListComponentMapEntry | Accesses the additive automatic components of this ACL. |
more_property_folders | bool | Are there more property folders? |
max_property_folders_limit | uint32 | The maximum property folders allowed. The server used this value to limit the returned property folders. If zero, the limit is infinite. |
more_objects | bool | Are there more objects? |
max_objects_limit | uint32 | The maximum objects allowed. The server used this value to limit the returned objects. If zero, the limit is infinite. |
more_external_view_folders | bool | Are there more external views? |
max_external_view_folders_limit | uint32 | The maximum external views allowed. The server used this value to limit the returned objects. If zero, the limit is infinite. |
psearchstatusflags | SEARCHSTATUSFLAGS | Receives search status flags. |
psearchstatusflags.all | bool | Specifies all flags set; Including any future flags. |
psearchstatusflags.multiphase_object_type_search_needed | bool | Multi-phase OT search is needed. |
psearchstatusflags.wildcard_expansion_limit_exceeded | bool | Wildcard expansion limit has been exceeded (but some results has been returned anyway). |
psearchstatusflags.may_contain_stale_data | bool | Data returned by search may be out of date. |
psearchstatusflags.resorted_to_default_sort | bool | Requested sorting is not supported and result set was established using the default sorting (relevance). |
psearchstatusflags.resorted_to_default_sort_too_many_results | bool | Requested sorting is not supported and result set was established using the default sorting (relevance) because there are too many matching results for sorting. |
psearchstatusflags.sorted_by_engine | bool | Data returned by search was sorted by the engine (Global Sorting). |
search_output_info | SearchOutputInfo | Additional information about the completed search operation. |
search_output_info.processing_time_at_engine_in_milliseconds | int32 | The processing time at the search engine, in milliseconds. -1 if not known. |
search_output_info.processing_time_at_engine_from_mfserver_in_milliseconds | int32 | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
search_output_info.processing_time_at_mfserver_in_milliseconds | int32 | The total processing time at MFServer, in milliseconds. -1 if not known. |
search_output_info.processing_time_at_mfserver_from_client_in_milliseconds | int32 | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
Related methods
- GetFolderContents -- Lists the contents of a view or a view level: subviews, grouping folders and objects.