## Methods

### create

##### splunkjs.Service.ConfigurationFile.create

##### Endpoint: configs/conf-{file}

Creates a stanza in this configuration file.

#### Syntax

create: function(stanzaName, values, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
stanzaName | String | A name for this stanza.
values | Object | A dictionary of key-value pairs to put in this stanza.
callback | Function | A function to call with the created stanza: `(err, createdStanza)`.

#### Examples

     var file = service.configurations().item("props");
     file.create("my_stanza", function(err, newStanza) {
         console.log("CREATED");
     });

#### Source (lib/service.js:2408)

    create: function(stanzaName, values, callback) {
            // If someone called us with the default style of (params, callback),
            // lets make it work
            if (utils.isObject(stanzaName) && utils.isFunction(values) && !callback) {
                callback = values;
                values = stanzaName;
                stanzaName = values.name;
            }

            if (utils.isFunction(values) && !callback) {
                callback = values;
                values = {};
            }

            values = values || {};
            values["name"] = stanzaName;

            return this._super(values, callback);
        }
    });

### init

##### splunkjs.Service.ConfigurationFile.init

Constructor for `splunkjs.Service.ConfigurationFile`.

#### Syntax

init: function(service, name, namespace)

#### Parameters

Name | Type | Description
--- | --- | ---
service | splunkjs.Service | A `Service` instance.
name | String | The name of the configuration file.
namespace | Object | Namespace information: - `owner` (string): The Splunk username, such as "admin". A value of "nobody" means no specific user. The "-" wildcard means all users. - `app` (string): The app context for this resource (such as "search"). The "-" wildcard means all apps. - `sharing` (string): A mode that indicates how the resource is shared. The sharing mode can be "user", "app", "global", or "system".

#### Return

splunkjs.Service.ConfigurationFile.

A new `splunkjs.Service.ConfigurationFile` instance.

#### Source (lib/service.js:2386)

    init: function(service, name, namespace) {
        this.name = name;
        this._super(service, this.path(), namespace);
    },

### instantiateEntity

##### splunkjs.Service.ConfigurationFile.instantiateEntity

Creates a local instance of a stanza in a configuration file.

#### Syntax

instantiateEntity: function(props)

#### Parameters

Name | Type | Description
--- | --- | ---
props | Object | The key-value properties for the new stanza.

#### Return

splunkjs.Service.ConfigurationStanza.

A new `splunkjs.Service.ConfigurationStanza` instance.

#### Source (lib/service.js:2367)

    instantiateEntity: function(props) {
        var entityNamespace = utils.namespaceFromProperties(props);
        return new root.ConfigurationStanza(this.service, this.name, props.name, entityNamespace);
    },

### path

##### splunkjs.Service.ConfigurationFile.path

Retrieves the REST endpoint path for this resource (with no namespace).

#### Syntax

path: function()

#### Source (lib/service.js:2355)

    path: function() {
        return Paths.configurations + "/conf-" + encodeURIComponent(this.name);
    },

## Inherited Methods

### del

##### splunkjs.Service.Endpoint.del

Performs a relative DELETE request on an endpoint's path, combined with the parameters and a relative path if specified.

#### Syntax

del: function(relpath, params, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
relpath | String | A relative path to append to the endpoint path.
params | Object | A dictionary of entity-specific parameters to add to the query string.
callback | Function | A function to call when the request is complete: `(err, response)`.

#### Examples

     // Will make a request to {service.prefix}/search/jobs/123456
     var endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
     endpoint.delete("", {}, function() { console.log("DELETED"))});

#### Source (lib/service.js:695)

    del: function(relpath, params, callback) {
            var url = this.qualifiedPath;
            // If we have a relative path, we will append it with a preceding
            // slash.
            if (relpath) {
                url = url + "/" + relpath;
            }
            return this.service.del(
                url,
                params,
                callback
            );
        }
    });

### fetch

##### splunkjs.Service.Collection.fetch

Refreshes the resource by fetching the object from the server and loading it.

#### Syntax

fetch: function(options, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
options | Object | A dictionary of collection filtering and pagination options: - `count` (integer): The maximum number of items to return. - `offset` (integer): The offset of the first item to return. - `search` (string): The search query to filter responses. - `sort_dir` (string): The direction to sort returned items: “asc” or “desc”. - `sort_key` (string): The field to use for sorting (optional). - `sort_mode` (string): The collating sequence for sorting returned items: “auto”, “alpha”, “alpha_case”, or “num”.
callback | Function | A function to call when the object is retrieved: `(err, resource)`.

#### Source (lib/service.js:1283)

    fetch: function(options, callback) {
        if (!callback && utils.isFunction(options)) {
            callback = options;
            options = {};
        }
        callback = callback || function() {};

        options = options || {};
        if (!options.count) {
            options.count = 0;
        }

        var that = this;
        var req = that.get("", options, function(err, response) {
            if (err) {
                callback(err);
            }
            else {
                that._load(response.data);
                callback(null, that);
            }
        });

        return req;
    },

### fetchOnEntityCreation

##### splunkjs.Service.Collection.fetchOnEntityCreation

A static property that indicates whether to call `fetch` after an entity has been created. By default, the entity is not fetched because the endpoint returns (echoes) the new entity.

#### Source (lib/service.js:1151)

    fetchOnEntityCreation: false,

### get

##### splunkjs.Service.Endpoint.get

Performs a relative GET request on an endpoint's path, combined with the parameters and a relative path if specified.

#### Syntax

get: function(relpath, params, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
relpath | String | A relative path to append to the endpoint path.
params | Object | A dictionary of entity-specific parameters to add to the query string.
callback | Function | A function to call when the request is complete: `(err, response)`.

#### Examples

     // Will make a request to {service.prefix}/search/jobs/123456/results?offset=1
     var endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
     endpoint.get("results", {offset: 1}, function() { console.log("DONE"))});

#### Source (lib/service.js:631)

    get: function(relpath, params, callback) {
        var url = this.qualifiedPath;
        // If we have a relative path, we will append it with a preceding
        // slash.
        if (relpath) {
            url = url + "/" + relpath;
        }
        return this.service.get(
            url,
            params,
            callback
        );
    },

### item

##### splunkjs.Service.Collection.item

Returns a specific entity from the collection.

#### Syntax

item: function(id, namespace)

#### Parameters

Name | Type | Description
--- | --- | ---
id | String | The name of the entity to retrieve.
namespace | Object | Namespace information: - `owner` (string): The Splunk username, such as "admin". A value of "nobody" means no specific user. The "-" wildcard means all users. - `app` (string): The app context for this resource (such as "search"). The "-" wildcard means all apps. - `sharing` (string): A mode that indicates how the resource is shared. The sharing mode can be "user", "app", "global", or "system".

#### Examples

     var apps = service.apps();
     apps.fetch(function(err, apps) {
         var app = apps.item("search");
         console.log("Search App Found: " + !!app);
         // `app` is an Application object.
     });

#### Source (lib/service.js:1330)

    item: function(id, namespace) {
        if (utils.isEmpty(namespace)) {
            namespace = null;
        }

        if (!id) {
            throw new Error("Must suply a non-empty name.");
        }

        var fullPath = null;
        if (this._entitiesByName.hasOwnProperty(id)) {
            var entities = this._entitiesByName[id];

            if (entities.length === 1 && !namespace) {
                // If there is only one entity with the
                // specified name and the user did not
                // specify a namespace, then we just
                // return it
                return entities[0];
            }
            else if (entities.length === 1 && namespace) {
                // If we specified a namespace, then we
                // only return the entity if it matches
                // the full path
                fullPath = this.service.fullpath(entities[0].path(), namespace);
                if (entities[0].qualifiedPath === fullPath) {
                    return entities[0];
                }
                else {
                    return null;
                }
            }
            else if (entities.length > 1 && !namespace) {
                // If there is more than one entity and we didn't
                // specify a namespace, then we return an error
                // saying the match is ambiguous
                throw new Error("Ambiguous match for name '" + id + "'");
            }
            else {
                // There is more than one entity, and we do have
                // a namespace, so we try and find it
                for(var i = 0; i < entities.length; i++) {
                    var entity = entities[i];
                    fullPath = this.service.fullpath(entities[i].path(), namespace);
                    if (entity.qualifiedPath === fullPath) {
                        return entity;
                    }
                }
            }
        }
        else {
            return null;
        }
    },

### links

##### splunkjs.Service.Collection.links

Retrieves the links information for this collection, which is the URI of the resource relative to the management port of a Splunk instance.

#### Syntax

links: function()

#### Return

Object.

The links information.

#### Source (lib/service.js:1242)

    links: function() {
        return this._links;
    },

### list

##### splunkjs.Service.Collection.list

Retrieves a list of all entities in the collection.

#### Syntax

list: function(callback)

#### Parameters

Name | Type | Description
--- | --- | ---
callback | Function | A function to call with the list of entities: `(err, list)`.

#### Examples

     var apps = service.apps();
     apps.fetch(function(err, apps) {
         var appList = apps.list();
         console.log(appList.length);
     });

#### Source (lib/service.js:1452)

    list: function(callback) {
            callback = callback || function() {};

            return utils.clone(this._entities);
        }
    });

### paging

##### splunkjs.Service.Collection.paging

Retrieves the author information for this collection.

#### Syntax

paging: function()

#### Return

String.

The author.

#### Source (lib/service.js:1253)

    paging: function() {
        return this._paging;
    },

### post

##### splunkjs.Service.Endpoint.post

Performs a relative POST request on an endpoint's path, combined with the parameters and a relative path if specified.

#### Syntax

post: function(relpath, params, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
relpath | String | A relative path to append to the endpoint path.
params | Object | A dictionary of entity-specific parameters to add to the body.
callback | Function | A function to call when the request is complete: `(err, response)`.

#### Examples

     // Will make a request to {service.prefix}/search/jobs/123456/control
     var endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
     endpoint.post("control", {action: "cancel"}, function() { console.log("CANCELLED"))});

#### Source (lib/service.js:663)

    post: function(relpath, params, callback) {
        var url = this.qualifiedPath;
        // If we have a relative path, we will append it with a preceding
        // slash.
        if (relpath) {
            url = url + "/" + relpath;
        }
        return this.service.post(
            url,
            params,
            callback
        );
    },

### properties

##### splunkjs.Service.Resource.properties

Retrieves the current properties for this resource.

#### Syntax

properties: function()

#### Return

Object.

The properties.

#### Source (lib/service.js:797)

    properties: function() {
        return this._properties;
    },

### state

##### splunkjs.Service.Resource.state

Retrieves the current full state (properties and metadata) of this resource.

#### Syntax

state: function()

#### Return

Object.

The current full state of this resource.

#### Source (lib/service.js:808)

    state: function() {
            return this._state;
        }
    });

### updated

##### splunkjs.Service.Collection.updated

Retrieves the updated time for this collection.

#### Syntax

updated: function()

#### Return

String.

The updated time.

#### Source (lib/service.js:1264)

    updated: function() {
        return this._updated;
    },