SAMP MTypes

This page discusses SAMP MTypes. MTypes define the semantics of messages exchanged between SAMP clients.

Introduction

An MType (Message Type) is the semantic label attached to a SAMP message (see SampInfo). An MType is a string which looks syntactically like a.b.c , and it has associated named parameters and return values - it can be thought of as a bit like a subroutine definition. More detailed and definitive discussion of MType syntax and usage can be found in the SAMP Standard.

MTypes fall into (about) three categories:

Administrative

MTypes beginning samp. have meanings concerned with the workings of the SAMP protocol itself. An example is samp.hub.event.register, which is broadcast whenever a new client registers with the hub. These are defined in the SAMP standard, and new ones may not in general be introduced at will.

Experimental administrative

MTypes beginning x-samp. are candidates for administrative ones. They are not currently part of the standard, but may be introduced in future versions of it, with the x-samp. replaced by samp. .

Application

In order for applications to communicate meaningfully they must agree on what MType to use for a given action. Public MTypes are ones agreed by several application authors with well-known meanings. An example is table.load.votable , which instructs to load a table in VOTable format at a given location. These are currently documented below.

Private

Any application author is free to introduce any MType for his/her own purposes, as long as it does not start with the reserved string " samp. ". In the case that this is for private testing, specialised communication between tools developed in the same place, or similar, there is no requirement to document these in a public fashion.

Process

An application author who needs to exchange an application-type message with particular semantics should proceed along the following lines:

1. Check the list below to see whether a suitable MType already exists
2. If not, or if one exists but needs adjustment such as new optional parameters, make or solicit suggestions on the form of a suitable MType on the apps-samp@ivoa.net mailing list
3. When some agreement is reached, add the documentation to the list below

The intention is that application MTypes, once added to this list, will continue to be used for the purpose for which they were introduced rather than being replaced by other differently-named ones of similar purpose. There may be amendments which involve addition of optional parameters or return values, on the understanding that they do not invalidate messages exchanged without knowledge of the new additions. In this way backward compatibility should be maintained.

This procedure is currently quite informal. It has worked well to date, but will remain under review. If the SAMP community decides that a change to the procedure is desirable, for instance publication of Application MTypes in an IVOA Note, or more structured review of suggestions, the new policy will be described here. This page may be reorganised at some point, for instance splitting the known Application MTypes into more than one list.

Application MTypes

The following MTypes are ones which application authors are using, or are considering using.

table.load.votable

• Arguments:
  • url (string): URL of the VOTable document to load
  • table-id (string) optional: identifier which may be used to refer to the loaded table in subsequent messages
  • name (string) optional: name which may be used to label the loaded table in the application GUI
• Return Values: none

table.load.fits

• Arguments:
  • url (string): URL of the FITS file to load
  • table-id (string) optional: identifier which may be used to refer to the loaded table in subsequent messages
  • name (string) optional: name which may be used to label the loaded table in the application GUI
• Return Values: none

table.highlight.row

• Arguments:
  • table-id (string): identifier associated with a table by a previous message (e.g. table.load.*)
  • url (string): URL of a table
  • row (SAMP int): Row index (zero-based) of the row to highlight.
• Return Values: none

table.select.rowList

• Arguments:
  • table-id (string): identifier associated with a table by a previous message (e.g. table.load.*)
  • url (string): URL of a table
  • row-list (list of SAMP int): list of row indices (zero-based) defining which table rows are to form the selection
• Return Values: none

image.load.fits

• Arguments:
  • url (string): URL of the FITS image to load
  • image-id (string) optional: Identifier which may be used to refer to the loaded image in subsequent messages
  • name (string) optional: name which may be used to label the loaded image in the application GUI
• Return Values: none

coord.pointAt.sky

• Arguments:
  • ra (SAMP float): right ascension in degrees
  • dec (SAMP float): declination in degrees
• Return Values: none

spectrum.load.ssa-generic

• Arguments:
  • url (string): URL of the spectrum to load
  • meta (map): Additional metadata describing the spectral data found at the URL. Key->Value pairs represent either Utypes or UCDs as defined or used in some version of the SSA specification or its predecessors. Example map keys are Access.Format (SSA 1.0 MIME type Utype) or VOX:Spectrum_Format (pre-1.0 SSA MIME type UCD). It is up to the recipient to make sense of these and, for instance, deal with the possibility that given expected keys are present or that apparently contradictory information is presented. Most existing SSA-aware spectrum viewing clients already contain this functionality.
  • spectrum-id (string) optional: Identifier which may be used to refer to the loaded spectrum in subsequent messages
  • name (string) optional: name which may be used to label the loaded spectrum in the application GUI
• Return Values: none

client.env.get

• Arguments:
  • name (string): environment variable name
• Return Values:
  • value (string): value of env variable "name" in receiver's environment

bibcode.load

• Arguments:
  • bibcode (string, required) the bibcode to load
• Return Values:
  • none

voresource.loadlist (and subtypes)

A registry resource is described by an xml document - a VOResource . Each registry resource is uniquely identified by a IVOID - a uri starting ivo://

• Subtypes: As well as the voresource.loadlist MType itself, which is appropriate for transmission of resources of any type, there are also specialised sub-MTypes for lists of particular resource types. Those currently defined are
  • voresource.loadlist.cone
  • voresource.loadlist.siap
  • voresource.loadlist.ssap
  • voresource.loadlist.tap
  • voresource.loadlist.vospace

• Arguments:
  • name: (string, optional) A descriptive name for this set of resources
  • ids: (required) A map of IVOID -> (optional) URL
    • The keys of this map are the IVO-identifiers of the voresources to load. The optional value associated with each key is an URL from which the XML of the voresource can be downloaded using a HTTP GET

• Return Values:
  • none

The URL values in the ids map are a convenience for receivers who may not possess a SOAP Registry client with which to retrieve the voresources themself. The URLs may also be useful in the case where the resource is only available in registry private to the sender, not in a registry known by the receiver.

However, the URL values are not mandatory, because to implement this, it may be necessary for the sender to create a local web-server - which is quite a demand for, say, a trivial script.

If the registry spec ever develops to provide a trival http / rest interface to resources, the URL values could link direct to this - but at the moment it's a work-around for the relative inaccessability of the registry SOAP interface.

Experimental Administrative MTypes

x-samp.query.by-meta

• Arguments:
  • key: (string, required) The metadata key of interest
  • value: (string, required) The value that key must have
• Return Values:
  • ids: (list of strings, required) A list containing the ID for each currently registered client whose metadata contains an entry with the given key and value (both treated case-sensitively). The list is empty if no such clients are registered.