Stations - AVDeskStation class¶
pyavdesk station resource described by AVDeskStation class exposes an interface to manipulate antivirus stations (PCs).
Note
It is advised to use server resource class AVDeskServer as a single entry point for every server resource manipulation instead of direct instantiation of AVDeskStation class.
Basic class usage example:
# Setting up server connection parameters.
av_server = pyavdesk.AVDeskServer('admin', 'password', 'http://192.168.1.70')
# Create a new station.
new_station = av_server.new_station()
new_station.save()
# Output generated station ID.
print new_station.id
- class pyavdesk.pyavdesk.AVDeskStation(connector_resource, resource_id=None, predefined_handle=None)¶
AV-Desk station resource class is used to perform stations manipulations.
Parameters: - connector_resource – should be AVDeskServer instance.
- resource_id – if set server call is performed to get information for resource with given ID.
- predefined_handle – if set, resource data could be fetched from a resource at given handle.
Raises: AVDeskError on failure
- add_emails(emails_list)¶
Adds given emails to a list of e-mails defined for the resource.
Note
This method does not send data to server, for this to be done one needs to save resource object.
Parameters: emails_list – list of e-mails Example:
resource_obj.add_emails(['person1@server.com', 'person2@server.com'])
- add_to_groups(groups_list)¶
Add groups to resource association by group IDs or objects.
Parameters: groups_list – list of AVDeskGroup instances, or a list of strings representing groups IDs Raises: AVDeskError on failure Note
Resource to group association is not sent to server until object’s save() is not called.
Warning
Some AV-Desk server versions (namely 6.2) might handle only one group per administrator. In that case only the first group from the given list is linked with the administrator.
Example:
resource_obj.add_to_groups(['my_group_id', my_another_group_obj]) resource_obj.save()
- create(auto_retrieve=True)¶
Performs a server call to create resource with properties defined in object.
Note
There is a convinience method save() to handle both create and update operations.
Parameters: auto_retrieve – boolean to specify whether an additional call to server is required after the create operation to retrieve full resource data. Default: True. Returns: True on success Raises: AVDeskError on failure Warning
Setting auto_retrieve to False may increase operation performance, but also may leave the resource object data in a not up-to-date state. It is advised that auto_retrieve set to False is only used when the resource object won’t be used further after the operation.
Example:
created = resource_obj.create()
- delete(**kwargs)¶
Performs server call in an attempt to delete the resource.
Returns: True on success Raises: AVDeskError on failure Example:
deleted = resource_obj.delete()
- delete_emails(emails_list)¶
Removes given emails from a list of e-mails defined for the resource.
Note
This method does not send data to server, for this to be done one needs to save resource object.
Parameters: emails_list – list of e-mails Example:
resource_obj.delete_emails(['person1@server.com', 'person2@server.com', 'person3@server.com'])
- delete_from_groups(groups_list)¶
Removes groups to resource association by group IDs or objects.
Parameters: groups_list – list of AVDeskGroup instances, or a list of strings representing groups IDs Raises: AVDeskError on failure Note
Resource to group association is not sent to server until object’s save() is not called.
Example:
resource_obj.delete_from_groups(['my_group_id', my_another_group_obj]) resource_obj.save()
- download_url¶
This property is used to get station’s download URL as string.
- expires_time¶
This property is used to get and set station’s expires datetime (as unix timestamp).
- get_av_bases()¶
Returns a list of antivirus bases used by station.
Returns: list of dictionaries with av bases data Raises: AVDeskError on failure Example:
av_bases = station.get_av_bases()
An extract from returned list:
[ { 'file_name': 'drw50001.vdb', 'created_ts': 1320059155, 'version': '500', 'viruses': 24512 }, ... ]
- get_av_components()¶
Performs a server call to retrieve a list of antivirus application components information for the resource.
Returns: list of dictionaries with components data Raises: AVDeskError on failure Example:
components = resource_obj.get_av_components()
An extract from returned list:
[ { 'status': 1, 'code': 105, 'parent_group_id': '2888b7ff-3625-465e-bcb8-957de17f6458', 'code_text': 'Dr.Web Firewall', 'status_text': 'Optional', ... }, ... ]
- get_av_components_installed()¶
Returns a list of antivirus application components installed at the station.
Returns: list of dictionaries with components data Raises: AVDeskError on failure Example:
installed = station.get_av_components_installed()
An extract from returned list:
[ { 'path': 'C:\Program Files\DrWeb AV-Desk', 'code': 103, 'code_text': 'Dr.Web Microsoft Outlook plugin', 'server': 'tcp/94.251.81.210:2193', 'installed_ts': 1320062616 }, ... ]
- get_av_components_running()¶
Returns a list of antivirus application components running at the station.
Returns: list of dictionaries with components data Raises: AVDeskError on failure Example:
running = station.get_av_components_running()
An extract from returned list:
[ { 'code': 30, 'code_text': 'Dr.Web AV-Desk Agent for Windows', 'started_ts': 1320523510, 'params': None, 'user': None, 'type': 8 }, ... ]
- get_av_modules()¶
Returns a list of antivirus modules used by the station.
Returns: list of dictionaries with modules data Raises: AVDeskError on failure Example:
modules = station.get_av_modules()
An extract from returned list:
[ { 'hash': '78a61d78e110fbf27975df4a4dc70dfc', 'name': 'Dr.Web(c) Scanner for Windows', 'created_ts': 1320062617, 'modified_ts': 1320062530, 'file_name': 'DRWEB32W.EXE', 'version': '6.00.11.7112', 'file_size': 2299656 }, ... ]
- get_av_packages()¶
Returns a list of antivirus agent download URLs for various platforms.
Returns: list of dictionaries with av packages data Raises: AVDeskError on failure Example:
av_packages = station.get_av_packages()
An extract from returned list:
[ { 'url': 'http://localhost/download/download.ds?id=some_id', 'type': 1 }, ... ]
- get_av_rights()¶
Performs a server call to retrieve a list of rights defined for the resource.
Returns: list of dictionaries with rigths data Raises: AVDeskError on failure Example:
rights = resource_obj.get_av_rights()
An extract from returned list:
[ { 'status': 1, 'code': 53, 'parent_group_id': '2888b7ff-3625-465e-bcb8-957de17f6458', 'code_text': 'Uninstall Dr.Web Agent', 'status_text': 'Enabled', ... }, ... ]
- get_block_time()¶
Returns a tuple with information about station blocking: begin and end unix timestamps.
Returns: list of dictionaries with modules data Raises: AVDeskError on failure Example:
start_at, finish_at = station.get_block_time()
- get_emails()¶
Returns a list of e-mails defined for the resource.
Returns: list of e-mails Example:
emails = resource_obj.get_emails()
- get_groups(as_id=True)¶
Performs a server call and returns a list of groups associated with the resource.
Parameters: as_id – boolean. If True list of AVDeskGroup instances is returned, if False - list of strings representing groups IDs Returns: list of objects which type is defined by as_id parameter Raises: AVDeskError on failure Note
Objects in the list returned have only basic information. To get full infomation use AVDeskGroup.retrieve_info().
Example:
groups = resource_obj.get_groups() for group in groups: print 'Group ID - %s' % group.id
- get_history(ts_from=0, ts_till=0, event_type_filter=None)¶
Performs a server call to retrieve station history information.
Parameters: - ts_from – timestamp of when history starts. If 0 - history starts at year 1970. Default 0.
- ts_till – timestamp of when history ends. If 0 - history ends today. Default 0.
- event_type_filter – event type identifier (see HISTORY_EVENT_TYPES) to filter history upon.
Returns: list of dictionaries with events data
Raises: AVDeskError on failure
Example:
history = station.get_history()
An extract from returned list:
[ { 'created_ts': 4294967295, 'action_ts': 4294967295, 'action_start_ts': 0, 'action_finish_ts': 0, 'tariff': None, 'tariff_name': None, 'event_type_id': 5 }, ... ]
- get_key()¶
Performs a server call to retrieve a dictionary with key information for the resource.
Returns: dictionary with key information Raises: AVDeskError on failure Example:
key = resource_obj.get_key()
An example of returned dictionary:
{ 'inherited_group_id': '20e27d73-d21d-b211-a788-85419c46f0e6', 'key': '=?ASCII?B?OyBEcldlYjMyIHY0LjE2?=' # This is a key in Base64 format. }
- get_parent(as_id=True)¶
Performs a server call to retrieve a parent resource for the current resource.
Parameters: as_id – boolean. If True resource object is returned, if False - resources’ ID Returns: object or ID. See as_id parameter. Raises: AVDeskError on failure Example:
parent = resource_obj.get_parent() print 'Parent ID - %s' % parent
- get_place_data()¶
Performs a server call to retrieve station’s place information as dictionary.
Returns: dictionary Raises: AVDeskError on failure Example:
place = station.get_place_data()
An extract from dictionary returned:
{ 'province': 'Academgorodok', 'city': 'Novosibirsk', 'street': 'Some street', 'room': None, 'organization': 'Doctor Web, Ltd.', 'latitude': 0, 'longitude': 0, 'country': 643, 'floor': None, 'department': None }
- get_resource_id()¶
Helper method to get resource identifier, which can be passed to such resource manipulation methods as get_info() and delete().
Returns: resource identifier as string
- get_statistics(ts_from=0, ts_till=0, virus_limit=10)¶
Makes request to a server and returns a dictionary with station statistics.
Parameters: - ts_from – timestamp of when statistics starts. If 0 - statistics starts at year 1970. Default 0.
- ts_till – timestamp of when staristics ends. If 0 - statistics ends today. Default 0.
- virus_limit – virus statistics limiter, to return no more than a given number of viruses. Default 10.
Returns: dictionary
Raises: AVDeskError on failure
Example:
stats = station.get_statistics()
An extract from dictionary returned:
{ 'viruses': [ { 'name': 'Trojan.Spambot', 'count': 3, 'objects_list': [ { 'originator': 57, 'originator_text': 'SpIDer Guard G3 for Workstations', 'owner': 'Unknown', ... }, ... ], }, 'scans': { 'files': 128, 'cured': 28, ... }, 'infections': { 'ignored': 0, 'errors': 0, 'deleted': 28, ... }, 'stations_total': 1, 'stations_state': { 'unactivated': 0, 'deinstalled': 0, 'online': 1, ... } }
- get_tariff(as_id=True)¶
Performs a server call to retrieve a tariff resource for the station.
Parameters: as_id – boolean. If True AVDeskTariff object is returned, if False - tariff ID Returns: object or ID. See as_id parameter. Raises: AVDeskError on failure Example:
tariff_id = resource_obj.get_tariff() print 'Station tariff ID - %s' % tariff_id
- grace_period¶
This property is used to get station’s grace period (in days) inherited from tariff group.
- key¶
Performs a server call to retrieve a dictionary with key information for the resource.
Returns: dictionary with key information Raises: AVDeskError on failure Example:
key = resource_obj.get_key()
An example of returned dictionary:
{ 'inherited_group_id': '20e27d73-d21d-b211-a788-85419c46f0e6', 'key': '=?ASCII?B?OyBEcldlYjMyIHY0LjE2?=' # This is a key in Base64 format. }
- last_seen_addr¶
This property is used to get station’s last seen network address as string.
- last_seen_time¶
This property is used to get station’s last seen unix timestamp.
- os¶
This property is used to get station’s OS as string.
- parent¶
Performs a server call to retrieve a parent resource for the current resource.
Parameters: as_id – boolean. If True resource object is returned, if False - resources’ ID Returns: object or ID. See as_id parameter. Raises: AVDeskError on failure Example:
parent = resource_obj.get_parent() print 'Parent ID - %s' % parent
- password¶
This property is used to get and station’s password.
- place_data¶
Performs a server call to retrieve station’s place information as dictionary.
Returns: dictionary Raises: AVDeskError on failure Example:
place = station.get_place_data()
An extract from dictionary returned:
{ 'province': 'Academgorodok', 'city': 'Novosibirsk', 'street': 'Some street', 'room': None, 'organization': 'Doctor Web, Ltd.', 'latitude': 0, 'longitude': 0, 'country': 643, 'floor': None, 'department': None }
- retrieve_info(resource_id=None)¶
Performs a server call to retrieve complete resource information by its ID and puts it into object’s properties.
Parameters: resource_id – specific ID of the resource. If None, ID is taken from the object itself. Raises: AVDeskError on failure Example:
# resource_obj contains no additional info. assert resource_obj.name is None # After the following request resource_obj.retrieve_info('some_resource_id') # resource_obj contains additional info. assert resource_obj.name is not None
- save(auto_retrieve=True)¶
A convinience method that automatically creates new resource on server if it doesn’t exists or updates it if it does.
Under the hood it switches between create() and update() methods.
Parameters: auto_retrieve – boolean to specify whether an additional call to server is required after the save operation to retrieve full resource data. Default: True. Returns: True on success Raises: AVDeskError on failure Warning
Setting auto_retrieve to False may increase operation performance, but also may leave the resource object data in a not up-to-date state. It is advised that auto_retrieve set to False is only used when the resource object won’t be used further after the operation.
Example:
saved = resource_obj.save()
- send_message(message_text, url='', url_text='', logo_abs_path='', logo_text='', logo_url='')¶
Sends a message to all group participants.
Parameters: - message_text – Message text which can contain {link} macros to place link given in link parameters to
- url – URL to be placed in {link} macros
- url_text – URL description text to be placed in {link} macros
- logo_abs_path – Absolute path to a logo .bmp file to show in message
- logo_text – Description text for a logo
- logo_url – URL to go to on a logo click
Returns: True on success
Raises: AVDeskError on failure
Example:
group.send_message('Hello from pyavdesk!')
- set_block_time(begin_at, finish_at)¶
Sets blocking information for the station.
Parameters: - begin_at – Block begin unix timestamp
- finish_at – Block end unix timestamp
Returns: True on success
Raises: AVDeskError on failure
Example:
station.set_block_time(start_at, finish_at)
- set_parent(id_or_obj)¶
Sets parent resource for the current resource.
Parameters: id_or_obj – Parent resource object or ID. Raises: AVDeskError on failure Example:
child_resource_obj.set_parent(parent_resource_obj) # Is equivalent to: child_resource_obj.set_parent('parent_resource_id')
- set_place_data(country=None, latitude=None, longitude=None, province=None, city=None, street=None, organization=None, department=None, floor=None, room=None)¶
Sets information about station’s place.
Parameters: - country – ISO numeric country code integer - (see http://en.wikipedia.org/wiki/ISO_3166-1_numeric)
- latitude – Latitude as integer
- longitude – Latitude as integer
- province – Province name string
- city – City name string
- street – Street name string
- organization – Organization name string
- department – Department name string
- floor – Floor string
- room – Room string
Example:
# Selectively set country and organization name for the station. station.set_place_data(country=643, organization='Doctor Web, Ltd.')
- set_tariff(id_or_obj)¶
Sets tariff for the current station.
Parameters: id_or_obj – Tariff resource object or ID. Raises: AVDeskError on failure Example:
station.set_tariff(tariff_resource_obj) # Is equivalent to: station.set_tariff('tariff_resource_id')
- state¶
This property is used to get station’s current state as string (e.g. online).
- statistics¶
Makes request to a server and returns a dictionary with station statistics.
Parameters: - ts_from – timestamp of when statistics starts. If 0 - statistics starts at year 1970. Default 0.
- ts_till – timestamp of when staristics ends. If 0 - statistics ends today. Default 0.
- virus_limit – virus statistics limiter, to return no more than a given number of viruses. Default 10.
Returns: dictionary
Raises: AVDeskError on failure
Example:
stats = station.get_statistics()
An extract from dictionary returned:
{ 'viruses': [ { 'name': 'Trojan.Spambot', 'count': 3, 'objects_list': [ { 'originator': 57, 'originator_text': 'SpIDer Guard G3 for Workstations', 'owner': 'Unknown', ... }, ... ], }, 'scans': { 'files': 128, 'cured': 28, ... }, 'infections': { 'ignored': 0, 'errors': 0, 'deleted': 28, ... }, 'stations_total': 1, 'stations_state': { 'unactivated': 0, 'deinstalled': 0, 'online': 1, ... } }
- tariff¶
Performs a server call to retrieve a tariff resource for the station.
Parameters: as_id – boolean. If True AVDeskTariff object is returned, if False - tariff ID Returns: object or ID. See as_id parameter. Raises: AVDeskError on failure Example:
tariff_id = resource_obj.get_tariff() print 'Station tariff ID - %s' % tariff_id
- update(auto_retrieve=True)¶
Performs server call in attempt to update the resource with information from class properties.
Note
There is a convinience method save() to handle both create and update operations.
Parameters: auto_retrieve – boolean to specify whether an additional call to server is required after the update operation to retrieve full resource data. Default: True. Returns: True on success Raises: AVDeskError on failure Warning
Setting auto_retrieve to False may increase operation performance, but also may leave the resource object data in a not up-to-date state. It is advised that auto_retrieve set to False is only used when the resource object won’t be used further after the operation.
Example:
updated = resource_obj.update()