Client

SAMPClientId

A simple structure to save the client ID of a SAMP client.

This structure contains a single string field, client_id. It is defined only to avoid type piracy and to resolve some parameter ambiguities in the code.

SAMPClient{H <: AbstractSAMPHub}

A structure representing a SAMP client.

The same structure is used for clients of a SAMPHub or of SAMPWebHub.

Members

• hub: the hub server
• name: the name of the client (compulsory)
• key: a string representing the secret key used by the client to contact the server
• hub_id: the id the hub has assigned to himself, as a SAMPClientId
• client_id: the id the hud has assigned to the client, as a SAMPClientId
• translator: the URL translator (only present if the server is a SAMPWebHub)
• hub_query_by_meta: a string that, if non-void, indicates the mtype accepted by the hub to perform queries by meta (can be "x-samp.query.by-meta" or "samp.query.by-meta")

Constructors

SAMPClient([hub,] name)
register([hub,] name [; metadata])

The first form simply create and register the client. The second form, register, also accepts metadata as keywords, which will be sent to the server (see setMetadata).

SAMPClient{H <: AbstractSAMPHub}

A structure representing a SAMP client.

The same structure is used for clients of a SAMPHub or of SAMPWebHub.

Members

• hub: the hub server
• name: the name of the client (compulsory)
• key: a string representing the secret key used by the client to contact the server
• hub_id: the id the hub has assigned to himself, as a SAMPClientId
• client_id: the id the hud has assigned to the client, as a SAMPClientId
• translator: the URL translator (only present if the server is a SAMPWebHub)
• hub_query_by_meta: a string that, if non-void, indicates the mtype accepted by the hub to perform queries by meta (can be "x-samp.query.by-meta" or "samp.query.by-meta")

Constructors

SAMPClient([hub,] name)
register([hub,] name [; metadata])

The first form simply create and register the client. The second form, register, also accepts metadata as keywords, which will be sent to the server (see setMetadata).

defaultClient::Union{SAMPClient,Nothing}

The default client.

Can be obtained (and set, if it is nothing) using getClient.

getClient()

Return the default client.

This function also sets it the first time it is called.

unregister([client])

Unregister client from the associated hub.

setMetadata([client]; metadata)
declareMetadata([client]; metadata)

Set the metadata associated with the client.

The metadata are passed as keyword arguments; metadata consisting of non-valid Julia keywords can be passed with the var"long.name" syntax. For example

setMetadata(client; var"samp.description.text"="A fast FITS image displayer")

Standard metadata can be entered using a shorter syntax. In particular, the following aliases are recognized

name => samp.name
description => samp.description.text
icon => samp.icon.url
documentation => samp.documentation.url

Note that, by design, if no icon is provided this function uses a standard icon; if no icon is desired, enter icon="" as keyword parameter.

If this function is called multiple times, the latest metadata are kept (all the others are discarded). Both functions are identical: declareMetadata is just an alias for setMetadata, kept to honour the original SAMP command.

setMetadata([client]; metadata)
declareMetadata([client]; metadata)

Set the metadata associated with the client.

The metadata are passed as keyword arguments; metadata consisting of non-valid Julia keywords can be passed with the var"long.name" syntax. For example

setMetadata(client; var"samp.description.text"="A fast FITS image displayer")

Standard metadata can be entered using a shorter syntax. In particular, the following aliases are recognized

name => samp.name
description => samp.description.text
icon => samp.icon.url
documentation => samp.documentation.url

Note that, by design, if no icon is provided this function uses a standard icon; if no icon is desired, enter icon="" as keyword parameter.

If this function is called multiple times, the latest metadata are kept (all the others are discarded). Both functions are identical: declareMetadata is just an alias for setMetadata, kept to honour the original SAMP command.

getMetadata([client,] dest=client.client_id)
getMetadata(dest)

Return the metadata set for the client dest.

getSubscriptions([client,] dest)

Return the subscriptions for the client dest.

getRegisteredClients([client])

Return a list of all clients registered with the hub of client.

getSubscribedClients([client,] mtype)

Return a list of all clients that subscribed to the given mtype.

notify([client,] dest, mtype [; args...])

Notify the message mtype with the optional arguments args to dest.

dest must be the ID of the destination client: this can be obtained from getSubscribedClients or getRegisteredClients.

The optional message arguments can be passed as keywords: as with setMetadata, arguments with non-valid Julia names can be entered as var"long.name"=value.

The alias communicate is used to avoid type piracy.

notifyAll([client,] mtype [; args...])

Notify the message mtype to all clients.

See also: notify

callAndWait([client,] dest, mtype; timeout=0 [, args...])

Send the message mtype to dest and wait for the reply.

Arguments to the message can be added as keywords, similarly to notify.

The timeout keyword controls the timeout in seconds: if set to 0 or to a negative number, there is no timeout (this is the default). Note that in this case the client can wait indefinitely.

findFirstClient([client,] name; key="samp.name")

Return the first client with the metadata key = name

Returns nothing if no client is found.

name can be a simple string (and then it must match exactly key), or a regular expression.

Equivalent to first(findFirstClient(client, name)), but with less allocations.

findAllClients([client,] name; key="samp.name")

Return all clients with the metadata key = name

name can be a simple string (and then it must match exactly key), or a regular expression.