`getdir` (Get metadata about a directory)

The getdir transaction returns meta information of a directory.

Query string

The query string in the HTTP header must contain the following parameters:

api

Specify the name of the API transaction.

apiversion

Specify the version of the API that should handle the requested transaction.

For the most up-to-date version, use apiversion=3.

uid

Specify a valid 1010data user name.

pswd

Specify a valid password for the 1010data user name provided to the uid parameter.

Note: The pswd value should be the encrypted password returned from the login transaction.

sid

The session ID for the current API session.

This value is returned by the login transaction and must be provided to every transaction (except login).

kill (optional)

Valid values for kill are as follows:

yes: Terminate the existing session and start a new one.
no: Do not terminate the existing session.
If no session exists, a new one will be created. If a session does exist, an error is returned.

Note: If kill=no and a session is active, the system returns an error.
possess: Log in and possess the existing session.
auth: Authenticate with the system but do not kill, possess, or start any session.

The default is yes.

XML Input to Server

The input specification for the transaction must contain the following elements:

<name>: The full name of the directory the transaction will request information about. See Folders and Tables Browser for additional information about directory and table names.

<include> (optional)

This optional element provides facility for specifying which specific metadata elements about the directory should be returned. Provide a list of <name> elements containing the names of the metadata elements that should be returned (e.g., <name>ldesc</name>. See the XML Response section of this topic for a complete list of metedata elements that may be returned by the transaction.

<include> also contains the mode attribute.

Use mode="1" to return metadata for parent and child directories.

Use mode="2" to only return information about child directories.

XML response from server

A successful response from the server contains the following elements:

<rc>: The return code generated by the transaction. For a list of return codes, see Return codes.
<msg>: The message returned by the system. Specific messages correspond to specific return codes.
<dir>: Contains data about parent and/or child objects in a directory.

The directory metadata is returned as a series of attributes contained within the <dir> element. The attributes are as follows:

id: The unique identification number for the directory, table, or query. The ID is an integer.
name: The full path to the table, directory, or query to which the metadata belongs.
title: The title, or label, of the directory, table, or query.
sdesc: The short description of the directory, table, or query.
ldesc: The long description of the directory, table, or query.
type: The type of the directory. Currently, all directories are of type dir.
secure: Returns 1 if the directory, table, or query is marked as "secure" and 0 if it is not marked as "secure".
Note: This metadata element is still returned but has been deprecated.
own: Boolean flag specifying whether the UID used for the API transaction is the owner of the directory.
owner: The owner of the directory, table, or query.
upload: Returns a 1 if the UID used for the API transaction has permission to add new objects to the directory. Returns a 0 if the UID does not.
update: The date and time the directory's metadata was last modified. If it was created and never modified, returns the date and time the directory was created.
gif: Returns the location of the gif file to be used to display the directory, table, or query in the UI.
users: A space-separated list of users and groups whom are allowed to access this directory, table, or query.
uploaders: Space-separated list of users and groups who have permission to create tables or directories inside the directory.
numchild: The number of child elements that descend from the directory specified.

Query string example

https://www2.1010data.com/gw.k?api=getdir&apiversion=3&uid=$UID&pswd=$PSWD&sid=$SID

XML Input Example

<in>
  <name>pub.demo.weather</name>
  <include mode="1">
    <name>ldesc</name>
    <name>sdesc</name>
    <name>type</name>
    <name>secure</name>
  </include>
</in>

XML response example

A successful getdir produces the following result:

<out>
    <rc>0</rc>
    <msg>getdir successful</msg>
    <dir sdesc="" ldesc="" type="DIR" secure="0"/>
</out>

getdir (Get metadata about a directory)