Inherits from NSObject
Declared in SCApiSession.h

Overview

The SCApiSession object provides support to perform the loading of system Items and their Fields from the backend.

All methods of this class can be divided into two general types.

  • asynchronous methods that load data from the backend. All such methods returns a block with SCExtendedAsyncOp type as a result.

  • synchronous “getters” methods. They are used for accessing loaded Items and Fields which are still in the memory cache.

SCExtendedApiSession object does not own loaded items and fields. However, they stay in memory cache as long as possible (until the memory warning occurs). You should keep a strong reference to the objects you need to make sure they survive the memory warning.

Items ( SCItem objects ) owns their descendant items and fields ( SCField objects ).

All methods of this class are not thread safe and they should be called exceptionally from one thread (main thread suggested)

Tasks

Properties

defaultDatabase

The database used to request Sitecore items, default is “web”.
It is also set for the corresponding SCExtendedApiSession object.

@property (nonatomic) NSString *defaultDatabase

Discussion

The database used to request Sitecore items, default is “web”.
It is also set for the corresponding SCExtendedApiSession object.

Declared In

SCApiSession.h

defaultImagesLifeTimeInCache

The default life time in cache after which object in cache becames old. Default value is one monce.
It is also set for the corresponding SCExtendedApiSession object.

@property (nonatomic) NSTimeInterval defaultImagesLifeTimeInCache

Discussion

The default life time in cache after which object in cache becames old. Default value is one monce.
It is also set for the corresponding SCExtendedApiSession object.

Declared In

SCApiSession.h

defaultItemVersion

The version used to request Sitecore items, default is “nil” which means the latest version will be retrieved.
It is also set for the corresponding SCExtendedApiSession object.

@property (nonatomic) NSString *defaultItemVersion

Discussion

The version used to request Sitecore items, default is “nil” which means the latest version will be retrieved.
It is also set for the corresponding SCExtendedApiSession object.

Declared In

SCApiSession.h

defaultLanguage

The language used to request Sitecore items, default is “en”.
It is also set for the corresponding SCExtendedApiSession object.

@property (nonatomic) NSString *defaultLanguage

Discussion

The language used to request Sitecore items, default is “en”.
It is also set for the corresponding SCExtendedApiSession object.

Declared In

SCApiSession.h

defaultLifeTimeInCache

The default life time in cache after which object in cache becames old. Default value is ten minutes.
It is also set for the corresponding SCExtendedApiSession object.

@property (nonatomic) NSTimeInterval defaultLifeTimeInCache

Discussion

The default life time in cache after which object in cache becames old. Default value is ten minutes.
It is also set for the corresponding SCExtendedApiSession object.

Declared In

SCApiSession.h

defaultSite

The site used to request Sitecore items, default is “nil”.
It is also set for the corresponding SCExtendedApiSession object.

@property (nonatomic) NSString *defaultSite

Discussion

The site used to request Sitecore items, default is “nil”.
It is also set for the corresponding SCExtendedApiSession object.

Declared In

SCApiSession.h

extendedApiSession

An instance of the corresponding SCExtendedApiSession that constructs cancellable operations.

@property (nonatomic, readonly) SCExtendedApiSession *extendedApiSession

Discussion

An instance of the corresponding SCExtendedApiSession that constructs cancellable operations.

Declared In

SCApiSession.h

mediaLibraryPath

Media library root folder in the content tree.
By default it is “/sitecore/media library”

@property (nonatomic) NSString *mediaLibraryPath

Discussion

Media library root folder in the content tree.
By default it is “/sitecore/media library”

Note : it must match the web.config settings on the back end.

It is also set for the corresponding SCExtendedApiSession object.

Declared In

SCApiSession.h

systemLanguages

The Sitecore system languages, by default is nil.
To read Sitecore system languages call [SCApiSession readSystemLanguagesOperation] method.

@property (nonatomic) NSSet *systemLanguages

Discussion

The Sitecore system languages, by default is nil.
To read Sitecore system languages call [SCApiSession readSystemLanguagesOperation] method.

Declared In

SCApiSession.h

Class Methods

defaultMediaLibraryPath

Default media library root folder in the content tree.

+ (NSString *)defaultMediaLibraryPath

Return Value

“/sitecore/media library”

Discussion

Default media library root folder in the content tree.

Declared In

SCApiSession.h

sessionWithHost:

Creates an anonymous session for the latest version of Item Web API.
It is used to read items and fields from Sitecore site as an anonymous user.

+ (id)sessionWithHost:(NSString *)host

Parameters

host

the host of Sitecore Item Web Api, example: “http://mobilesdk.sc-demo.net:80”

Return Value

existing SCApiSession object for the given host or new created one if it doesn’t exist

Discussion

Creates an anonymous session for the latest version of Item Web API.
It is used to read items and fields from Sitecore site as an anonymous user.

You can create the only one SCApiSession object for the one set of options host, login and password, it means that if you try to create another SCApiSession object with the same host, login and password, just previous created SCApiSession object for this host will be returned.

It can be expressed this an example: [SCApiSession sessionWithHost: someHost] == [SCApiSession sessionWithHost: someHost] returns TRUE.

But SCApiSession object is not a “singleton”, if you have no any SCItem, SCField object in memory and any other entity does not retain SCApiSession object - it will be released.

Declared In

SCApiSession.h

sessionWithHost:login:password:

Creates an authenticated session for the latest version of Item Web API.
It is used to read items and fields from Sitecore site as given user.

+ (id)sessionWithHost:(NSString *)host login:(NSString *)login password:(NSString *)password

Parameters

host

the host of Sitecore Item Web Api, example: “http://mobilesdk.sc-demo.net:80”

login

the domain and login of the given user. For example, @“extranet\JohnDoe”.
If “sitecore” domain is used, the proper site should be specified either in requests or for the context.

See [SCApiSession defaultSite] and [SCBaseItemRequest site] properties for more details.

password

the user’s password.

Return Value

existing SCApiSession object for the given host or new created one if it doesn’t exist

Discussion

Creates an authenticated session for the latest version of Item Web API.
It is used to read items and fields from Sitecore site as given user.

You can create the only one SCApiSession object for the one set of options host, login and password, it means that if you try to create another SCApiSession object with the same host, login and password, just previous created SCApiSession object for this host will be returned.

It can be expressed this an example: [SCApiSession sessionWithHost: someHost] == [SCApiSession sessionWithHost: someHost] returns TRUE.

But SCApiSession object is not a “singleton”, if you have no any SCItem, SCField object in memory and any other entity does not retain SCApiSession object - it will be released.

Declared In

SCApiSession.h

sessionWithHost:login:password:version:

Returns SCApiSession’s instance with a Sitecore Item Web Api host, login and password.
Used to read items and fields as authenticated user with given login and password from Sitecore site.

+ (id)sessionWithHost:(NSString *)host login:(NSString *)login password:(NSString *)password version:(SCWebApiVersion)webApiVersion

Parameters

host

the host of Sitecore Item Web Api, example: “http://mobilesdk.sc-demo.net:80”

login

the domain and login of the given user. For example, @“extranet\JohnDoe”.
If “sitecore” domain is used, the proper site should be specified either in requests or for the context.
See [SCApiSession defaultSite] and [SCBaseItemRequest site] properties for more details.

password

the user’s password.

webApiVersion

the target version of Item Web API. See SCWebApiVersion enum for details. At the moment only one version of ItemWebAPI is available. It contains “v1” in all HTTP requests.

Discussion

Returns SCApiSession’s instance with a Sitecore Item Web Api host, login and password.
Used to read items and fields as authenticated user with given login and password from Sitecore site.

You can create the only one SCApiSession object for the one set of options: host, login and password, it means that if you try to create another SCApiSession object with the same host, login and passwor, just previous created SCApiSession object for this host will be returned.

It can be expressed this an example: [SCApiSession sessionWithHost: someHost] == [SCApiSession sessionWithHost: someHost] returns TRUE.

But SCApiSession object is not a “singleton”, if you have no any SCItem, SCField object in memory and any other entity does not retain SCApiSession object - it will be released.

Declared In

SCApiSession.h

sessionWithHost:version:

Creates an anonymous session targeting a particular version of ItemWebApi.
It is used to read items and fields from Sitecore site as given user.

+ (id)sessionWithHost:(NSString *)host version:(SCWebApiVersion)webApiVersion

Parameters

host

the host of Sitecore Item Web Api, example: “http://mobilesdk.sc-demo.net:80”

webApiVersion

the target version of Item Web API. See SCWebApiVersion enum for details. At the moment only one version of ItemWebAPI is available. It contains “v1” in all HTTP requests.

Return Value

existing SCApiSession object for the given host or new created one if it doesn’t exist

Discussion

Creates an anonymous session targeting a particular version of ItemWebApi.
It is used to read items and fields from Sitecore site as given user.

You can create the only one SCApiSession object for the one set of options host, login and password, it means that if you try to create another SCApiSession object with the same host, login and password, just previous created SCApiSession object for this host will be returned.

It can be expressed this an example: [SCApiSession sessionWithHost: someHost] == [SCApiSession sessionWithHost: someHost] returns TRUE.

But SCApiSession object is not a “singleton”, if you have no any SCItem, SCField object in memory and any other entity does not retain SCApiSession object - it will be released.

Declared In

SCApiSession.h

Instance Methods

checkCredentialsOperationForSite:

Used to check if a user with given name and password exists on the instance.
The callback gets NSNull on success and nil on error.

- (SCAsyncOp)checkCredentialsOperationForSite:(NSString *)site

Parameters

site

name of the site, set up on the instance. Site name must start with a slash. For example, @“/sitecore/shell”. Pass “nil” for the default site.

Return Value

SCAsyncOp block. Call it to get the expected result.

Discussion

Used to check if a user with given name and password exists on the instance.
The callback gets NSNull on success and nil on error.

Declared In

SCApiSession.h

cleanupItemsCache

This method wipes out all cached items. Cached requests won’t be affected though.
Use this method if you need to perform a memory intensive operation efficiently. It should help you avoiding unwanted memory warning interrupts.

- (void)cleanupItemsCache

Discussion

This method wipes out all cached items. Cached requests won’t be affected though.
Use this method if you need to perform a memory intensive operation efficiently. It should help you avoiding unwanted memory warning interrupts.

Declared In

SCApiSession.h

createItemsOperationWithRequest:

Used to create item according to the properties of SCCreateItemRequest object

- (SCAsyncOp)createItemsOperationWithRequest:(SCCreateItemRequest *)createItemRequest

Parameters

createItemRequest

SCCreateItemRequest object which provides a bunch of options to create item

Return Value

SCAsyncOp block. Call it to create item. The SCAsyncOpResult handler’s result is SCItem object or nil if error happens.

Discussion

Used to create item according to the properties of SCCreateItemRequest object

Declared In

SCApiSession.h

deleteItemsOperationWithRequest:

Used to remove existing items found with SCReadItemsRequest request.

- (SCAsyncOp)deleteItemsOperationWithRequest:(SCReadItemsRequest *)request

Parameters

request

SCReadItemsRequest object which provides a bunch of options to find items to remove.

Return Value

SCAsyncOp block. Call it to edit items. The SCAsyncOpResult handler’s result is NSArray of removed items ids or nil if error happens.

Discussion

Used to remove existing items found with SCReadItemsRequest request.

Declared In

SCApiSession.h

downloadResourceOperationForMediaPath:

Used to load image with the image path, see [SCImageField imagePath].

- (SCAsyncOp)downloadResourceOperationForMediaPath:(NSString *)path

Parameters

path

image’s path. Image with http://{WebApiHost}/~/media{path}.ashx will be loaded.

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is UIImage object or nil if error happens.

Discussion

Used to load image with the image path, see [SCImageField imagePath].

Declared In

SCApiSession.h

downloadResourceOperationForMediaPath:imageParams:

Used to load image with the image path, see [SCImageField imagePath] with additional parameters.

- (SCAsyncOp)downloadResourceOperationForMediaPath:(NSString *)path imageParams:(SCDownloadMediaOptions *)params

Parameters

path

image’s path. Image with http://{WebApiHost}/~/media{path}.ashx will be loaded.

params

Options for image processing on the server side before downloading. The most frequent use case is resizing images. For more details see SCDownloadMediaOptions class.

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is UIImage object or nil if error happens.

Discussion

Used to load image with the image path, see [SCImageField imagePath] with additional parameters.

Declared In

SCApiSession.h

editItemsOperationWithRequest:

Used to edit existing items according to the properties of SCEditItemsRequest object

- (SCAsyncOp)editItemsOperationWithRequest:(SCEditItemsRequest *)editItemsRequest

Parameters

editItemsRequest

SCEditItemsRequest object which provides a bunch of options to edit items

Return Value

SCAsyncOp block. Call it to edit items. The SCAsyncOpResult handler’s result is NSArray of edited SCItem objects or nil if error happens.

Discussion

Used to edit existing items according to the properties of SCEditItemsRequest object

Declared In

SCApiSession.h

fieldWithName:itemId:

Returns SCField object for the given items’s ID and field’s name if such field was loaded and the item has a field with such name

- (SCField *)fieldWithName:(NSString *)fieldName itemId:(NSString *)itemId

Parameters

fieldName

the name of item’s field name, see [SCField name]

itemId

system item’s id, [SCItem itemId] can be used.

Return Value

SCField object or nil if such field does not exists.

Discussion

Returns SCField object for the given items’s ID and field’s name if such field was loaded and the item has a field with such name

Declared In

SCApiSession.h

fieldWithName:itemId:source:

Returns SCField object for the given items’s ID, item’s source and field’s name if such field was loaded and the item has a field with such name

- (SCField *)fieldWithName:(NSString *)fieldName itemId:(NSString *)itemId source:(id<SCItemSource>)itemSource

Parameters

fieldName

the name of item’s field name, see [SCField name]

itemId

system item’s id, [SCItem itemId] can be used.

itemSource

source of the item. This is a place to specify a database, a site, etc.

Return Value

SCField object or nil if such field does not exists.

Discussion

Returns SCField object for the given items’s ID, item’s source and field’s name if such field was loaded and the item has a field with such name

Declared In

SCApiSession.h

getRenderingHtmlOperationForRenderingWithId:sourceId:

Used to request rendering HTML for rendering with pointed id and item id presented using rendering.
Uses defauld language and database of SCApiSession

- (SCAsyncOp)getRenderingHtmlOperationForRenderingWithId:(NSString *)renderingId sourceId:(NSString *)sourceId

Parameters

renderingId
  • id of rendering which you want to request
sourceId
  • item’s id for render using rendering with renderingId

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is NSString object or nil if error happens.

Discussion

Used to request rendering HTML for rendering with pointed id and item id presented using rendering.
Uses defauld language and database of SCApiSession

Declared In

SCApiSession.h

getRenderingHtmlOperationWithRequest:

Used to request rendering HTML.

- (SCAsyncOp)getRenderingHtmlOperationWithRequest:(SCGetRenderingHtmlRequest *)request

Parameters

request

contains the information about

  • rendering item id
  • rendering datasource item id
  • source of both the rendering and the datasource. See SCItemSource protocol for more details

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is NSString object or nil if error happens.

Discussion

Used to request rendering HTML.

Declared In

SCApiSession.h

itemWithId:

Returns SCItem object with a given items’s ID if such system item was loaded and still exists in the memory

- (SCItem *)itemWithId:(NSString *)itemId

Parameters

itemId

system item’s id, [SCItem itemId] can be used.

Return Value

SCItem object or nil if such item does not exists.

Discussion

Returns SCItem object with a given items’s ID if such system item was loaded and still exists in the memory

Declared In

SCApiSession.h

itemWithId:source:

Returns SCItem object with a given items’s ID and source if such system item was loaded and still exists in the memory

- (SCItem *)itemWithId:(NSString *)itemId source:(id<SCItemSource>)itemSource

Parameters

itemId

system item’s id, [SCItem itemId] can be used.

itemSource

source of the item. This is a place to specify a database, a site, etc.

Return Value

SCItem object or nil if such item does not exists.

Discussion

Returns SCItem object with a given items’s ID and source if such system item was loaded and still exists in the memory

Declared In

SCApiSession.h

itemWithPath:

Returns SCItem object with a given items’s path if such system item was loaded and still exists in the memory

- (SCItem *)itemWithPath:(NSString *)path

Parameters

path

system item’s path, [SCItem path] or string (for example “/sitecore/content”).

Return Value

SCItem object or nil if such item does not exists.

Discussion

Returns SCItem object with a given items’s path if such system item was loaded and still exists in the memory

Declared In

SCApiSession.h

itemWithPath:source:

Returns SCItem object with a given items’s path and source if such system item was loaded and still exists in the memory

- (SCItem *)itemWithPath:(NSString *)path source:(id<SCItemSource>)itemSource

Parameters

path

system item’s path, [SCItem path] or string (for example “/sitecore/content”).

itemSource

source of the item. This is a place to specify a database, a site, etc.

Return Value

SCItem object or nil if such item does not exists.

Discussion

Returns SCItem object with a given items’s path and source if such system item was loaded and still exists in the memory

Declared In

SCApiSession.h

readChildrenOperationForItemId:

Used to load item’s children by the system item id.

- (SCAsyncOp)readChildrenOperationForItemId:(NSString *)itemId

Parameters

itemId

system item’s id, [SCItem itemId] can be used.

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is NSArray of SCItem objects or nil if error happens.

Discussion

Used to load item’s children by the system item id.

Declared In

SCApiSession.h

readChildrenOperationForItemPath:

Used to load item’s children by the system item id.

- (SCAsyncOp)readChildrenOperationForItemPath:(NSString *)path

Parameters

path

system item’s path, [SCItem path] or string (for example “/sitecore/content”).

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is NSArray of SCItem objects or nil if error happens.

SCAsyncOpResult handler may return such errors:

Discussion

Used to load item’s children by the system item id.

Declared In

SCApiSession.h

readFieldsByNameForItemId:

Returns loaded fields for the given item.

- (NSDictionary *)readFieldsByNameForItemId:(NSString *)itemId

Parameters

itemId

system item’s id, [SCItem itemId] can be used.

Return Value

loaded fields for the given item. It is a NSDictionary of SCField objects by field’s names.

Discussion

Returns loaded fields for the given item.

Declared In

SCApiSession.h

readFieldsByNameForItemId:source:

Returns loaded fields for the item with the specified id from the given source.

- (NSDictionary *)readFieldsByNameForItemId:(NSString *)itemId source:(id<SCItemSource>)itemSource

Parameters

itemId

system item’s id, [SCItem itemId] can be used.

itemSource

source of the item. This is a place to specify a database, a site, etc.

Return Value

loaded fields for the given item. It is a NSDictionary of SCField objects by field’s names.

Discussion

Returns loaded fields for the item with the specified id from the given source.

Declared In

SCApiSession.h

readItemOperationForFieldsNames:itemId:

Used to load item with fields by the system item id.

- (SCAsyncOp)readItemOperationForFieldsNames:(NSSet *)fieldNames itemId:(NSString *)itemId

Parameters

fieldNames

the set of field’s names which will be read with the item. Each field’s name in set should be a string.
For reading all fields - pass nil or pass empty set if you don’t need to read any field

itemId

system item’s id, [SCItem itemId] can be used.

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is SCItem object or nil if error happens.

SCAsyncOpResult handler may return such errors:

Discussion

Used to load item with fields by the system item id.

Declared In

SCApiSession.h

readItemOperationForFieldsNames:itemPath:

Used to load item with fields by the system item id.

- (SCAsyncOp)readItemOperationForFieldsNames:(NSSet *)fieldNames itemPath:(NSString *)path

Parameters

fieldNames

the set of field’s names which will be read with the item. Each field’s name in set should be a string.
For reading all fields - pass nil or pass empty set if you don’t need to read any field

path

system item’s path, [SCItem path] or string (for example “/sitecore/content”).

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is SCItem object or nil if error happens.

SCAsyncOpResult handler may return such errors:

Discussion

Used to load item with fields by the system item id.

Declared In

SCApiSession.h

readItemOperationForFieldsNames:itemSource:itemId:

Used to load item with fields by the system item id from the given source.

- (SCAsyncOp)readItemOperationForFieldsNames:(NSSet *)fieldNames itemSource:(id<SCItemSource>)itemSource itemId:(NSString *)itemId

Parameters

fieldNames

the set of field’s names which will be read with the item. Each field’s name in set should be a string.
For reading all fields - pass nil or pass empty set if you don’t need to read any field

itemSource

source of the item. This is a place to specify a database, a site, etc.

itemId

system item’s id, [SCItem itemId] can be used.

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is SCItem object or nil if error happens.

SCAsyncOpResult handler may return such errors:

Discussion

Used to load item with fields by the system item id from the given source.

Declared In

SCApiSession.h

readItemOperationForItemId:

Used to load item from the backend with a given system item ID

- (SCAsyncOp)readItemOperationForItemId:(NSString *)itemId

Parameters

itemId

system item’s id, [SCItem itemId] can be used.

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is SCItem object or nil if error happens.

If Sitecore Item Web Api(backend) does not return any item, SCNoItemError error will be returned by SCAsyncOpResult handler.

Discussion

Used to load item from the backend with a given system item ID

Declared In

SCApiSession.h

readItemOperationForItemPath:

Used for the reading item from a backend with a given system item path

- (SCAsyncOp)readItemOperationForItemPath:(NSString *)path

Parameters

path

system item’s path, [SCItem path] or string (for example “/sitecore/content”).

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is SCItem object or nil if error happens.

SCAsyncOpResult handler may return such errors:

Discussion

Used for the reading item from a backend with a given system item path

Declared In

SCApiSession.h

readItemsOperationWithRequest:

Used to load items from the backend according to the properties of SCReadItemsRequest object

- (SCAsyncOp)readItemsOperationWithRequest:(SCReadItemsRequest *)request

Parameters

request

SCReadItemsRequest object which provides a bunch of options to load items from the backend or getting already loaded items

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is NSArray of SCItem objects or nil if error happens.

Discussion

Used to load items from the backend according to the properties of SCReadItemsRequest object

Declared In

SCApiSession.h

readSystemLanguagesOperation

Used to load Sitecore system languages from the backend.

- (SCAsyncOp)readSystemLanguagesOperation

Return Value

SCAsyncOp block. Call it to get the expected result. The SCAsyncOpResult handler’s result is NSSet of strings or nil if error happens.

Discussion

Used to load Sitecore system languages from the backend.

Declared In

SCApiSession.h

triggerOperationWithRequest:

Used to trigger a goal or a campain with the given request

- (SCAsyncOp)triggerOperationWithRequest:(SCTriggeringRequest *)request

Parameters

request

A triggering request. See SCTrafficTriggeringRequest and SCCampaignTriggeringRequest for details

Return Value

SCAsyncOp block. Call it to trigger either a goal or a campaign. The SCAsyncOpResult handler’s result is an NSString that contains the rendering of the item (an HTML web page).

Discussion

Used to trigger a goal or a campain with the given request

Declared In

SCApiSession.h

uploadMediaOperationWithRequest:

Used to create media item according to the properties of SCUploadMediaItemRequest object

- (SCAsyncOp)uploadMediaOperationWithRequest:(SCUploadMediaItemRequest *)createMediaItemRequest

Parameters

createMediaItemRequest

SCUploadMediaItemRequest object which provides a bunch of options to create media item

Return Value

SCAsyncOp block. Call it to create media item. The SCAsyncOpResult handler’s result is SCItem object or nil if error happens.

Discussion

Used to create media item according to the properties of SCUploadMediaItemRequest object

Declared In

SCApiSession.h