collaboration.file module

binaryninja.collaboration.file.RemoteFile(handle)

Class representing a remote project file.

class RemoteFile(handle: LP_BNRemoteFile)

Bases: object

Class representing a remote project file. It controls the various snapshots and raw file contents associated with the analysis.

Parameters:

handle (LP_BNRemoteFile) –

create_snapshot(name: str, contents: bytes, analysis_cache_contents: bytes, file: bytes, parent_ids: ~typing.List[str], progress: ~typing.Callable[[int, int], bool] = <function nop>) → CollabSnapshot

Create a new snapshot on the remote (and pull it)

Parameters:

• name (str) – Snapshot name

• contents (bytes) – Snapshot contents

• analysis_cache_contents (bytes) – Contents of analysis cache of snapshot

• file (bytes) – New file contents (if contents changed)

• parent_ids (List[str]) – List of ids of parent snapshots (or empty if this is a root snapshot)

• progress (Callable[[int, int], bool]) – Function to call on progress updates

Returns:

Reference to the created snapshot

Raises:

RuntimeError if there was an error

Return type:

CollabSnapshot

delete_snapshot(snapshot: CollabSnapshot)

Delete a snapshot from the remote

Parameters:

snapshot (CollabSnapshot) – Snapshot to delete

Raises:

RuntimeError if there was an error

download(progress: ~typing.Callable[[int, int], bool] = <function nop>) → bytes

Download the contents of a remote file

Parameters:

progress (Callable[[int, int], bool]) – Function to call on progress updates

Returns:

Contents of the file

Raises:

RuntimeError if there was an error

Return type:

bytes

download_to_bndb(path: str | None = None, progress: ~typing.Callable[[int, int], bool] = <function nop>) → FileMetadata

Download a remote file and save it to a bndb at the given path. This calls databasesync.download_file and self.sync to fully prepare the bndb.

Parameters:

• path (str | None) – Path to new bndb to create

• progress (Callable[[int, int], bool]) – Function to call on progress updates

Returns:

Constructed FileMetadata object

Raises:

RuntimeError if there was an error

Return type:

FileMetadata

static get_for_bv(bv: BinaryView) → RemoteFile | None

Look up the remote File for a local BinaryView, or None if there is no matching remote File found.

Parameters:

bv (BinaryView) – Local BinaryView

Returns:

Remote File object

Return type:

File or None

static get_for_local_database(database: Database) → RemoteFile | None

Look up the remote File for a local database, or None if there is no matching remote File found. See get_for_bv to load from a BinaryView.

Parameters:

database (Database) – Local database

Returns:

Remote File object

Return type:

File or None

get_snapshot_by_id(id: str) → CollabSnapshot | None

Get a specific Snapshot in the File by its id

Note

If snapshots have not been pulled, they will be pulled upon calling this.

Parameters:

id (str) – Id of Snapshot

Returns:

Snapshot object, if one with that id exists. Else, None

Raises:

RuntimeError if there was an error pulling snapshots

Return type:

CollabSnapshot | None

pull(bv_or_db: BinaryView | Database, conflict_handler: util.ConflictHandlerType, progress: util.ProgressFuncType = <function nop>, name_changeset: util.NameChangesetFuncType = <function nop>)

Pull updated snapshots from the remote. Merge local changes with remote changes and potentially create a new snapshot for unsaved changes, named via name_changeset.

Parameters:

• bv_or_db (BinaryView | Database) – Binary view or database to sync with

• conflict_handler (util.ConflictHandlerType) – Function to call to resolve snapshot conflicts

• name_changeset (util.NameChangesetFuncType) – Function to call for naming a pushed changeset, if necessary

• progress (util.ProgressFuncType) – Function to call for progress updates

Raises:

RuntimeError – If there was an error (or the operation was cancelled)

pull_snapshots(progress: ~typing.Callable[[int, int], bool] = <function nop>)

Pull the list of Snapshots from the Remote.

Parameters:

progress (Callable[[int, int], bool]) – Function to call for progress updates

Raises:

RuntimeError if there was an error pulling snapshots

push(bv_or_db: ~binaryninja.binaryview.BinaryView | ~binaryninja.database.Database, progress: ~typing.Callable[[int, int], bool] = <function nop>)

Push locally added snapshots to the remote

Parameters:

• bv_or_db (BinaryView | Database) – Binary view or database to sync with

• progress (Callable[[int, int], bool]) – Function to call for progress updates

Raises:

RuntimeError – If there was an error (or the operation was cancelled)

sync(bv_or_db: BinaryView | Database, conflict_handler: util.ConflictHandlerType, progress: util.ProgressFuncType = <function nop>, name_changeset: util.NameChangesetFuncType = <function nop>)

Completely sync a file, pushing/pulling/merging/applying changes

Parameters:

• bv_or_db (BinaryView | Database) – Binary view or database to sync with

• conflict_handler (util.ConflictHandlerType) – Function to call to resolve snapshot conflicts

• name_changeset (util.NameChangesetFuncType) – Function to call for naming a pushed changeset, if necessary

• progress (util.ProgressFuncType) – Function to call for progress updates

Raises:

RuntimeError – If there was an error (or the operation was cancelled)

property chat_log_url: str

Chat log api endpoint URL

Returns:

URL string

property core_file: ProjectFile

property created: datetime

Created date of the file

Returns:

Date object

property default_path: str

Get the default filepath for a remote File. This is based off the Setting for collaboration.directory, the file’s id, the file’s project’s id, and the file’s remote’s id.

Returns:

Default file path

Return type:

str

property description: str

Description of the file

Returns:

Description string

property folder: RemoteFolder | None

Parent folder, if one exists. None if this is in the root of the project.

Returns:

Folder object or None

property has_pulled_snapshots: bool

If the file has pulled the snapshots yet

Returns:

True if they have been pulled

property hash: str

Hash of file contents (no algorithm guaranteed)

Returns:

Hash string

property id: str

Unique id

Returns:

Id string

property last_modified: datetime

Last modified date of the file

Returns:

Date object

property last_snapshot: datetime

Date of last snapshot in the file

Returns:

Date object

property last_snapshot_by: str

Username of user who pushed the last snapshot in the file

Returns:

Username string

property name: str

Displayed name of file

Returns:

Name string

property project: RemoteProject

Owning Project

Returns:

Project object

property remote: Remote

Owning Remote

Returns:

Remote object

property size: int

Size of raw content of file, in bytes

Returns:

Size in bytes

property snapshots: List[CollabSnapshot]

Get the list of snapshots in this file.

Note

If snapshots have not been pulled, they will be pulled upon calling this.

Returns:

List of Snapshot objects

Raises:

RuntimeError if there was an error pulling snapshots

property type: RemoteFileType

File Type All files share the same properties, but files with different types may make different uses of those properties, or not use some of them at all.

Returns:

Type of file on server (enum)

property url: str

Web api endpoint URL

Returns:

URL string