1. Calling Plugins

This chapter describes the structure of SOAP calls to CartoWeb server methods in order to obtain cartographic data.

Warning

Due to some CartoWeb evolutions, please note that some parts of the current chapter may need some updates!

Global WSDL code can be found in file CARTOWEB_HOME/server/cartoserver.wsdl. WSDL code specific to plugins are located in PLUGIN_HOME/common/plugin_name.wsdl.inc. Interesting parts from these files are copied in the following sections.

Complete WSDL code dynamically generated for a map ID is accessible at the URL CARTOWEB_URL/cartoserver.wsdl.php?mapId=project_name.mapfile_name.

SOAP method getMapInfo is used to retrieve server configuration information, such as available layers, initial state, etc.. It shouldn't be called each time a map is requested. A mechanism based on a timestamp is available to be sure configuration is up-to-date (see Section 1.2, “Call to getMapInfo”).

SOAP method getMap is used each time a new map or related information are needed.

1.1. Standard Structures

1.1.1. Simple Types

These types are used in different other structures.

<complexType name="ArrayOfString">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="xsd:string[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of character strings

<complexType name="Dimension">
  <all>
    <element name="width" type="xsd:int"/>
    <element name="height" type="xsd:int"/>
  </all>
</complexType>

width - width in pixels
height - height in pixels

<complexType name="GeoDimension">
  <all>
    <element name="dimension" type="types:Dimension"/>
    <element name="bbox" type="types:Bbox"/>
  </all>
</complexType>

dimension - dimensions in pixels
bbox - bounding box (see Section 1.1.2, “Shapes” for a description of type Bbox)

1.1.2. Shapes

These types define a hierarchy of shapes. As heritage and polymorphism cannot be used, type Shape includes all attibutes of its children types.

<complexType name="Bbox">
  <all>
    <element name="minx" type="xsd:double"/>
    <element name="miny" type="xsd:double"/>
    <element name="maxx" type="xsd:double"/>
    <element name="maxy" type="xsd:double"/>
  </all>
</complexType>

minx - minimum x coordinate
miny - minimum y coordinate
maxx - maximum x coordinate
maxy - maximum y coordinate

<complexType name="Point">
  <all>
    <element name="x" type="xsd:double"/>
    <element name="y" type="xsd:double"/>
  </all>
</complexType>

x - x coordinate
y - y coordinate

<complexType name="ArrayOfPoint">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Point[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of points

<complexType name="Shape">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="x" type="xsd:double" minOccurs="0"/>
    <element name="y" type="xsd:double" minOccurs="0"/>
    <element name="minx" type="xsd:double" minOccurs="0"/>
    <element name="miny" type="xsd:double" minOccurs="0"/>
    <element name="maxx" type="xsd:double" minOccurs="0"/>
    <element name="maxy" type="xsd:double" minOccurs="0"/>
    <element name="points" type="types:ArrayOfPoint" minOccurs="0"/>
  </all>
</complexType>

className - shape class name: "Point", "Bbox", "Rectangle", "Line" or "Polygon"
x - x coordinate (Point)
y - y coordinate (Point)
minx - minimum x coordinate (Bbox or Rectangle)
miny - minimum y coordinate (Bbox or Rectangle)
maxx - maximum x coordinate (Bbox or Rectangle)
maxy - maximum y coordinate (Bbox or Rectangle)
points - list of points (Line or Polygon)

<complexType name="ArrayOfShape">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Shape[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of shapes

1.1.3. Tables

These types define a table structure, used in particular in Query plugin (see Section 1.3.6, “Query”).

<complexType name="TableRow">
  <all>
    <element name="rowId" type="xsd:string"/>
    <element name="cells" type="types:ArrayOfString"/>
  </all>
</complexType>

rowId - row ID
cells - cell contents (see Section 1.1.1, “Simple Types” for a description of type ArrayOfString)

<complexType name="ArrayOfTableRow">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:TableRow[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of rows

<complexType name="Table">
  <all>
    <element name="tableId" type="xsd:string"/>
    <element name="tableTitle" type="xsd:string"/>
    <element name="numRows" type="xsd:integer"/>
    <element name="totalRows" type="xsd:integer"/>
    <element name="offset" type="xsd:integer"/>
    <element name="columnIds" type="types:ArrayOfString"/>
    <element name="columnTitles" type="types:ArrayOfString"/>
    <element name="noRowId" type="xsd:boolean"/>
    <element name="rows" type="types:ArrayOfTableRow"/>
  </all>
</complexType>

tableId - table ID
tableTitle - table title
numRows - number of rows in table
totalRows - total number of rows in context (for future use)
offset - current position in context rows (for future use)
columnIds - column IDs (see Section 1.1.1, “Simple Types” for a description of type ArrayOfString)
columnTitles - column titles (see Section 1.1.1, “Simple Types” for a description of type ArrayOfString)
noRowId - if true, table rows contain no row IDs
rows - list of rows

<complexType name="ArrayOfTable">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Table[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of tables

<complexType name="TableGroup">
  <all>
    <element name="groupId" type="xsd:string"/>
    <element name="groupTitle" type="xsd:string"/>
    <element name="tables" type="types:ArrayOfTable"/>
  </all>
</complexType>

groupId - ID of table group
groupTitle - title of table group
tables - list of tables

<complexType name="ArrayOfTableGroup">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:TableGroup[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of table groups

<complexType name="TableFlags">
  <all>
    <element name="returnAttributes" type="xsd:boolean"/>
    <element name="returnTable" type="xsd:boolean"/>
  </all>
</complexType>

returnAttributes - if true, will return attributes (row cells) in addition to row IDs
returnTable - if false, won't return any table information. This can be useful for instance when hilighting an object on which no information is needed

1.2. Call to getMapInfo

This method returns server configuration, which includes layers, initial states and other plugin-specific configuration. Variables returned by this method are set in server configuration files described in Part II, “User Manual”.

1.2.1. Global Server Configuration

This includes layers configuration and initial states.

<complexType name="LayerState">
  <all>
    <element name="id" type="xsd:string"/>
    <element name="hidden" type="xsd:boolean"/>
    <element name="frozen" type="xsd:boolean"/>
    <element name="selected" type="xsd:boolean"/>
    <element name="unfolded" type="xsd:boolean"/>
  </all>
</complexType>

id - layer state ID
hidden - if true, layer isn't displayed in tree and attribute selected cannot be modified
frozen - if true, layer is displayed in tree but attribute selected cannot be modified
selected - if true, layer is displayed as selected in tree
unfolded - if true, layer tree is displayed unfolded (layer groups)

<complexType name="ArrayOfLayerState">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:LayerState[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of layer states

<complexType name="InitialLocation">
  <all>
    <element name="bbox" type="types:Bbox"/>
  </all>
</complexType>

bbox - initial bounding box (see Section 1.1.2, “Shapes” for a description of type Bbox)

<complexType name="InitialMapState">
  <all>
    <element name="id" type="xsd:string"/>
    <element name="location" type="types:InitialLocation"/>
    <element name="layers" type="types:ArrayOfLayerState"/>
  </all>
</complexType>

id - initial state ID
location - initial location
layers - list of layer states

<complexType name="ArrayOfInitialMapState">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:InitialMapState[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of initial states

<complexType name="MapInfo">
  <all>
    <element name="timestamp" type="xsd:integer"/>
    <element name="mapLabel" type="xsd:string"/>
    <element name="keymapGeoDimension" type="types:GeoDimension"/>
    <element name="initialMapStates"
             type="types:ArrayOfInitialMapState"/>
    ...elements specific to plugins...
  </all>
</complexType>

timestamp - timestamp of last update. This timestamp is transferred each time method getMap is called, so client knows when configuration was modified (see also Section 1.3.1.1, “Global Request”)
mapLabel - name of map as defined in mapfile
keymapGeoDimension - pixel and geographical dimension information for key map
initialMapStates - list of initial states

1.2.2. Layers

This includes configuration specific to Layers plugin, ie. list of all available layers and their properties.

<complexType name="ArrayOfLayerId">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="xsd:string[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of layer IDs

<complexType name="ChildrenSwitch">
  <all>
    <element name="id" type="xsd:string"/>
    <element name="layers" type="types:ArrayOfLayerId" minOccurs="0"/>
  </all>
</complexType>

id - switch ID
layers - list of layers

<complexType name="ArrayOfChildrenSwitch">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType=ChildrenSwitch[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of children switches

<complexType name="Layer">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="id" type="xsd:string"/>
    <element name="label" type="xsd:string"/>
    <element name="children"
             type="types:ArrayOfChildrenSwitch" minOccurs="0"/>
    <element name="minScale" type="xsd:double"/>
    <element name="maxScale" type="xsd:double"/>
    <element name="icon" type="xsd:string"/>
    <element name="link" type="xsd:string"/>
    <element name="aggregate" type="xsd:boolean" minOccurs="0"/>
    <element name="rendering" type="xsd:string" minOccurs="0"/>
    <element name="metadata" type="types:ArrayOfString" minOccurs="0"/>
  </all>
</complexType>

className - layer class name: "LayerGroup", "Layer" or "LayerClass"
id - layer ID
label - label to be displayed. This label is not yet translated using internationalization
children - list of children
minScale - minimum scale at which layer will be displayed
maxScale - maximum scale at which layer will be displayed
icon - filename of the static icon for the layer. Dynamic legends are described in Section 6.4, “Layers Legends”
link - if set, layer name is clickable
msLayer - MapServer layer id
aggregate - if true, children are not displayed and cannot be selected individually
rendering - how layer will be displayed: "tree", "block", "radio" or "dropdown". See Chapter 6, Layers for more details on this option
metadata - list of meta data defined in server configuration file. Format of each string in list is "variable_name=value"

<complexType name="ArrayOfLayer">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Layer[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of layers

<complexType name="SwitchInit">
  <all>
    <element name="id" type="xsd:string"/>
    <element name="label" type="xsd:string"/>
  </all>
</complexType>

id - switch ID
label - switch label

<complexType name="ArrayOfSwitchInit">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:SwitchInit[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of switches

<complexType name="LayersInit">
  <all>
    <element name="notAvailableIcon" type="xsd:string"/>
    <element name="notAvailablePlusIcon" type="xsd:string"/>
    <element name="notAvailableMinusIcon" type="xsd:string"/>
    <element name="layers" type="types:ArrayOfLayer"/>
    <element name="switches" type="types:ArrayOfSwitchInit" minOccurs="0"/>
  </all>
</complexType>

notAvailableIcon - filename of icon for not available layer (current scale is above or below this layer maximum/minimum scale)
notAvailablePlusIcon - filename of icon for not available layer (current scale is above this layer maximum scale)
notAvailableMinusIcon - filename of icon for not available layer (current scale is below this layer minimum scale)
layers - list of layers
switches - list of switches

1.2.3. Location

This includes configuration specific to Location plugin, ie. fixed scales, scales limits and shortcuts.

<complexType name="LocationScale">
  <all>
    <element name="label" type="xsd:string"/>
    <element name="value" type="xsd:double"/>
  </all>
</complexType>

label - scale caption
value - scale value to be set when scale is selected

<complexType name="ArrayOfLocationScale">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:LocationScale[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of scales

<complexType name="LocationShortcut">
  <all>
    <element name="label" type="xsd:string"/>
    <element name="bbox" type="types:Bbox"/>
  </all>
</complexType>

label - shortcut caption
bbox - bounding box to recenter on when shortcut is selected

<complexType name="ArrayOfLocationShortcut">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:LocationShortcut[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of shortcuts

<complexType name="LocationInit">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="scales" type="types:ArrayOfLocationScale"/>
    <element name="minScale" type="xsd:double"/>
    <element name="maxScale" type="xsd:double"/>
    <element name="shortcuts" type="types:ArrayOfLocationShortcut"/>
  </all>
</complexType>

className - "LocationInit" or extended class name if project implements an extension
scales - list of fixed scales
minScale - global minimum scale
maxScale - global maximum scale
shortcuts - list of bounding box shortcuts

1.2.4. Layer Reorder

This includes configuration specific to LayerReorder plugin.

<complexType name="LayerReorderInit">
  <all>
    <element name="layers" type="types:ArrayOfLayerInit"/>
  </all>
</complexType>

array - layers are ordered from top to bottom of the displayed stack, see below to LayerInit structure overview.

<complexType name="LayerInit">
  <all>
    <element name="layerId" type="xsd:string"/>
    <element name="layerLabel" type="xsd:string"/>
  </all>
</complexType>

layerId - Layer Id
layerLabel - label to be displayed. This label is not yet translated using internationalization

1.3. Call to getMap

For each plugin, SOAP XML format are described for both server calls (i.e. requests) and server results.

1.3.1. Global Structures

Below is a description of general requests and results which include plugin-specific ones.

1.3.1.1. Global Request

<complexType name="MapRequest">
  <all>
    <element name="mapId" type="xsd:string"/>
    ...elements specific to plugins...
  </all>
</complexType>

mapId - map ID, ie. project name and mapfile name separated by a point

1.3.1.2. Global Result

<complexType name="Message">
  <all>
    <element name="channel" type="xsd:integer"/>
    <element name="message" type="xsd:string"/>
  </all>
</complexType>

channel - type of message: 1 = end user, 2 = developer
message - text of the message

<complexType name="ArrayOfMessage">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Message[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of messages

<complexType name="MapResult">
  <all>
    <element name="timestamp" type="xsd:integer"/>
    <element name="serverMessages"
             type="types:ArrayOfMessage" minOccurs="0"/>
    ...elements specific to plugins...
  </all>
</complexType>

timestamp - timestamp which identifies the server configuration. If this timestamp changes, it means server configuration changed and a call to method getMapInfo is required to get latest version (see Section 1.2, “Call to getMapInfo”).
serverMessages - list of messages returned by server

1.3.2. Images

The Images plugin generates MapServer images. The three types of images are main map, key map and scale bar. Basic parameters, such as image size, are defined in this request/result. More specific parameters, such as map location or content, are defined in other plugins.

1.3.2.1. Images Request

<complexType name="Image">
  <all>
    <element name="isDrawn" type="xsd:boolean"/>
    <element name="path" type="xsd:string"/>
    <element name="width" type="xsd:int"/>
    <element name="height" type="xsd:int"/>
  </all>
</complexType>

isDrawn - true if the image should be generated (when used in a request) or if it was generated (when returned in a result)
path - relative path of generated image. Not used in request
width - image width
height - image height

<complexType name="ImagesRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="mainmap" type="types:Image"/>
    <element name="keymap" type="types:Image"/>
    <element name="scalebar" type="types:Image"/>
  </all>
</complexType>

className - "ImagesRequest" or extended class name if project implements an extension
mainmap - main map image information
keymap - key map image information
scalebar - scale bar image information

1.3.2.2. Images Result

<complexType name="ImagesResult">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="mainmap" type="types:Image"/>
    <element name="keymap" type="types:Image"/>
    <element name="scalebar" type="types:Image"/>
  </all>
</complexType>

className - "ImagesResult" or extended class name if project implements an extension
mainmap - main map image information (see Section 1.3.2.1, “Images Request” for a description of type Image)
keymap - key map image information
scalebar - scale bar image information

1.3.3. Layers

The Layers plugin handles layers selection. Its request object includes list of layers to be displayed on main map. This plugin has no specific result object.

1.3.3.1. Layers Request

<complexType name="LayersRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="layerIds" type="types:ArrayOfLayerId"/>
    <element name="resolution" type="xsd:int"/>
    <element name="switchId" type="xsd:string"/>
  </all>
</complexType>

className - "LayersRequest" or extended class name if project implements an extension
layerIds - list of layers to include in map generation (see Section 1.1.1, “Simple Types” for a description of type ArrayOfLayerId)
resolution - MapServer resolution. Set this to null if you want to use default resolution
switchId - current switch ID

1.3.3.2. Layers Result

<complexType name="LayersResult">
  <all>
    <element name="className" type="xsd:string"/>
  </all>
</complexType>

className - "LayersResult" or extended class name if project implements an extension

1.3.4. Layer Reorder

The LayerReorder plugin handles layers reorder selection. Its request object includes list of layerIds rightly ordered to be displayed on main map. This plugin has no specific result object.

1.3.4.1. Layer Reorder Request

<complexType name="LayersRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="layerIds" type="types:ArrayOfLayerId"/>
  </all>
</complexType>

className - "LayerReorderRequest" or extended class name if project implements an extension
layerIds - list of layers to include in map generation rightly ordered from top to bottom (see Section 1.1.1, “Simple Types” for a description of type ArrayOfLayerId).

1.3.5. Location

The Location plugin handles position and moves on the map. Its request process includes different position methods, such as recentering on a specific object or moves relative to previous position. It returns the new bounding box and scale.

1.3.5.1. Location Request

<simpleType name="LocationType">
  <restriction base="xsd:string">
    <enumeration value="bboxLocationRequest"/>
    <enumeration value="panLocationRequest"/>
    <enumeration value="zoomPointLocationRequest"/>
    <enumeration value="recenterLocationRequest"/>
  </restriction>
</simpleType>

bboxLocationRequest - recenters on a bounding box
panLocationRequest - moves horizontaly/verticaly (panning)
zoomPointLocationRequest - recenters on a point, includes relative zoom and fixed scale
recenterLocationRequest - recenters on mapfile IDs

<complexType name="LocationConstraint">
  <all>
    <element name="maxBbox" type="types:Bbox"/>
  </all>
</complexType>

maxBbox - maximum bounding box. If given parameters lead to a larger bounding box, it will be cropped (see Section 1.1.2, “Shapes” for a description of type Bbox)

<complexType name="LocationRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="locationType"  type="types:LocationType"/>
    <element name="bboxLocationRequest"
             type="types:BboxLocationRequest" minOccurs="0"/>
    <element name="panLocationRequest"
             type="types:PanLocationRequest" minOccurs="0"/>
    <element name="zoomPointLocationRequest"
             type="types:ZoomPointLocationRequest" minOccurs="0"/>
    <element name="recenterLocationRequest"
             type="types:RecenterLocationRequest" minOccurs="0"/>
    <element name="locationConstraint"
             type="types:LocationConstraint" minOccurs="0"/>
  </all>
</complexType>

className - "LocationRequest" or extended class name if project implements an extension
locationType - type of location
bboxLocationRequest - bounding box request parameters (see Section 1.3.5.1.1, “BBox Request”)
panLocationRequest - panning request parameters (see Section 1.3.5.1.2, “Pan Request”)
zoomPointLocationRequest - zoom, recenter on point parameters (see Section 1.3.5.1.3, “Zoom-Point Request”)
recenterLocationRequest - recenter on IDs parameters (see Section 1.3.5.1.4, “Recenter Request”)
locationConstraint - constraint to be respected when location request is executed

1.3.5.1.1. BBox Request

<complexType name="BboxLocationRequest">
  <all>
    <element name="bbox" type="types:Bbox"/>
  </all>
</complexType>

bbox - bounding box to be recentered on (see Section 1.1.2, “Shapes” for a description of type Bbox)

1.3.5.1.2. Pan Request

<simpleType name="PanDirectionType">
  <restriction base="xsd:string">
    <enumeration value="VERTICAL_PAN_NORTH"/>
    <enumeration value="VERTICAL_PAN_NONE"/>
    <enumeration value="VERTICAL_PAN_SOUTH"/>
    <enumeration value="HORIZONTAL_PAN_WEST"/>
    <enumeration value="HORIZONTAL_PAN_NONE"/>
    <enumeration value="HORIZONTAL_PAN_EAST"/>
  </restriction>
</simpleType>

VERTICAL_PAN_NORTH - panning north
VERTICAL_PAN_NONE - no vertical panning
VERTICAL_PAN_SOUTH - panning south
HORIZONTAL_PAN_WEST - panning west
HORIZONTAL_PAN_NONE - no horizontal panning
HORIZONTAL_PAN_EAST - panning east

<complexType name="PanDirection">
  <all>
    <element name="verticalPan" type="types:PanDirectionType"/>
    <element name="horizontalPan" type="types:PanDirectionType"/>
  </all>
</complexType>

verticalPan - type of vertical panning
horizontalPan - type of horizontal panning

<complexType name="PanLocationRequest">
  <all>
    <element name="bbox" type="types:Bbox"/>
    <element name="panDirection" type="types:PanDirection"/>
  </all>
</complexType>

bbox - current bounding box (see Section 1.1.2, “Shapes” for a description of type Bbox)
panDirection - panning directions

1.3.5.1.3. Zoom-Point Request

<simpleType name="ZoomType">
  <restriction base="xsd:string">
    <enumeration value="ZOOM_DIRECTION_IN"/>
    <enumeration value="ZOOM_DIRECTION_NONE"/>
    <enumeration value="ZOOM_DIRECTION_OUT"/>
    <enumeration value="ZOOM_FACTOR"/>
    <enumeration value="ZOOM_SCALE"/>
  </restriction>
</simpleType>

ZOOM_DIRECTION_IN - zoom in (default is x2)
ZOOM_DIRECTION_NONE - no zoom, recenter on point only
ZOOM_DIRECTION_OUT - zoom out (default is x0.5)
ZOOM_FACTOR - zoom using a custom factor
ZOOM_SCALE - zoom to a fixed scale

<complexType name="ZoomPointLocationRequest">
  <all>
    <element name="bbox" type="types:Bbox"/>
    <element name="point" type="types:Point"/>
    <element name="zoomType" type="types:ZoomType"/>
    <element name="zoomFactor" type="xsd:float" minOccurs="0"/>
    <element name="scale" type="xsd:integer" minOccurs="0"/>
  </all>
</complexType>

bbox - bounding box (unused when zoom type = ZOOM_SCALE)
point - point to recenter on
zoomType - type of zoom
zoomFactor - zoom factor (unused when zoom type != ZOOM_FACTOR)
scale - fixed scale (unused when zoom type != ZOOM_SCALE)

1.3.5.1.4. Recenter Request

<complexType name="IdSelection">
  <all>
    <element name="layerId" type="xsd:string"/>
    <element name="idAttribute" type="xsd:string"/>
    <element name="idType" type="xsd:string"/>
    <element name="selectedIds" type="types:ArrayOfString"/>
  </all>
</complexType>

layerId - ID of layer on which query will be executed
idAttribute - name of ID attribute
idType - type of ID attribute ("string" or "int")
selectedIds - list of IDs

<complexType name="ArrayOfIdSelection">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:IdSelection[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of ID selections

<complexType name="RecenterLocationRequest">
  <all>
    <element name="idSelections" type="types:ArrayOfIdSelection"/>
  </all>
</complexType>

idSelections - list of ID selections

1.3.5.2. Location Result

<complexType name="LocationResult">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="bbox" type="types:Bbox"/>
    <element name="scale" type="xsd:double"/>
  </all>
</complexType>

className - "LocationResult" or extended class name if project implements an extension
bbox - new bounding box (see Section 1.1.2, “Shapes” for a description of type Bbox)
scale - new scale

1.3.6. Query

The Query plugin allows to search objects, hilight them on map and return text results. Search can be executed from a rectangle selection and/or using a list of object IDs.

Query request object is not mandatory. For more information about Query plugin, see Chapter 9, Queries.

1.3.6.1. Query Request

<simpleType name="QuerySelectionPolicy">
  <restriction base="xsd:string">
    <enumeration value="POLICY_XOR"/>
    <enumeration value="POLICY_UNION"/>
    <enumeration value="POLICY_INTERSECTION"/>
  </restriction>
</simpleType>

POLICY_XOR - XOR selection: when selecting a group of objects, already selected ones are unselected and not yet selected ones are selected (default type)
POLICY_UNION - union selection: when selecting a group of objects, already selected ones are kept selected and not yet selected ones are selected
POLICY_INTERSECTION - intersection selection: when selecting a group of objects, only already selected ones are kept selected

<complexType name="QuerySelection">
  <all>
    <element name="layerId" type="xsd:string"/>
    <element name="idAttribute" type="xsd:string"/>
    <element name="idType" type="xsd:string"/>
    <element name="selectedIds" type="types:ArrayOfString"/>
    <element name="useInQuery" type="xsd:boolean"/>
    <element name="policy" type="types:QuerySelectionPolicy"/>
    <element name="maskMode" type="xsd:boolean"/>
    <element name="hilight" type="xsd:boolean"/>
    <element name="tableFlags" type="types:TableFlags"/>
  </all>
</complexType>

layerId - layer ID on which query will be executed
idAttribute - name of ID attribute
idType - type of ID attribute ("string" or "int")
selectedIds - list of IDs
useInQuery - if true, will force query to use this layer
policy - type of selection
maskMode - if true, will apply a mask instead of a simple selection. This won't work when using MapServer's hilighting feature (see Chapter 9, Queries)
hilight - if false, selection won't be hilighted on map
tableFlags - table flags (see Section 1.1.3, “Tables” for a description of type TableFlags)

<complexType name="ArrayOfQuerySelection">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:QuerySelection[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of query selections

<complexType name="QueryRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="shape" type="types:Shape"/>
    <element name="queryAllLayers" type="xsd:boolean"/>
    <element name="defaultMaskMode" type="xsd:boolean"/>
    <element name="defaultHilight" type="xsd:boolean"/>
    <element name="defaultTableFlags" type="types:TableFlags"/>
    <element name="querySelections" type="types:ArrayOfQuerySelection"/>
  </all>
</complexType>

className - "QueryRequest" or extended class name if project implements an extension
shape - type of query object dependant. It can be a bounding box, a polygon, a circle or a point (see Section 1.1.2, “Shapes” for a description of differents types)
queryAllLayers - if true, will execute query on all selected layers, ie. layers sent through Layers request (see Section 1.3.3.1, “Layers Request”). Unused when bounding box is not specified
defaultMaskMode - mask mode for new layers (returned by query and but not yet in array querySelections). Unused when queryAllLayers = false
defaultHilight - highlight for new layers (returned by query and but not yet in array querySelections). Unused when queryAllLayers = false
defaultTableFlags - table flags for new layers (returned by query and but not yet in array querySelections, see Section 1.1.3, “Tables” for a description of type TableFlags). Unused when queryAllLayers = false
querySelections - list if query selections. It contains all objects that must be hilighted and can be used to maintain persistence of a selection

1.3.6.2. Query Result

<complexType name="QueryResult">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="tableGroup" type="types:TableGroup"/>
  </all>
</complexType>

className - "QueryResult" or extended class name if project implements an extension
tableGroup - group of tables which contains query results (one table per layer)

1.3.7. Outline

The Outline plugin allows to draw shapes on the main map. Shapes can also be drawn as a mask, ie. as holes in a rectangle covering map. It returns total area covered by shapes.

Outline request is not mandatory. As Outline plugin is not a core plugin, it must be activated in order to use the following request/result objects.

1.3.7.1. Outline Request

<complexType name="Color">
  <all>
    <element name="r" type="xsd:int"/>
    <element name="g" type="xsd:int"/>
    <element name="b" type="xsd:int"/>
  </all>
</complexType>

r - red
g - green
b - blue

<complexType name="ShapeStyle">
  <all>
    <element name="symbol" type="xsd:int"/>
    <element name="size" type="xsd:int"/>
    <element name="color" type="types:Color"/>
    <element name="outlineColor" type="types:Color"/>
    <element name="backgroundColor" type="types:Color"/>
    <element name="transparency" type="xsd:int"/>
  </all>
</complexType>

symbol -index of Mapserver symbol
size - size of shape
color - color
outlineColor - outline color
backgroundColor - background color
transparency - transparency

<complexType name="LabelStyle">
  <all>
    <element name="font" type="xsd:int"/>
    <element name="size" type="xsd:int"/>
    <element name="color" type="types:Color"/>
    <element name="outlineColor" type="types:Color"/>
    <element name="backgroundColor" type="types:Color"/>
  </all>
</complexType>

font - index of Mapserver font
size - size of font
color - color
outlineColor - outline color
backgroundColor - background color

<complexType name="StyledShape">
  <all>
    <element name="shapeStyle" type="types:ShapeStyle"/>
    <element name="labelStyle" type="types:LabelStyle"/>
    <element name="shape" type="types:Shape"/>
    <element name="label" type="xsd:string"/>
  </all>
</complexType>

shapeStyle - style of shape
labelStyle - style of label
shape - shape (can be a point, rectangle, line or polygon, see Section 1.1.2, “Shapes” for a description of type Shape)
label - content of label

<complexType name="ArrayOfStyledShape">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:StyledShape[]"/>
    </restriction>
  </complexContent>
</complexType>

array - list of shapes with style

<complexType name="OutlineRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="shapes" type="types:ArrayOfStyledShape"/>
    <element name="maskMode" type="xsd:boolean"/>
  </all>
</complexType>

className - "OutlineRequest" or extended class name if project implements an extension
shapes - list of styled shapes
maskMode - if true, will draw the complement of all shapes merged together

1.3.7.2. Outline Result

<complexType name="OutlineResult">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="area" type="xsd:double"/>
  </all>
</complexType>

className - "OutlineResult" or extended class name if project implements an extension
area - total area for all shapes

1.4. Examples

The following examples show simple SOAP calls using PHP.

To use these examples with your CartoWeb server, you'll have to modify the map ID and the layer names. Please note that in these examples, access to resources uses symbolic links (see Chapter 4, Configuration Files).

1.4.1. Retrieving Server Configuration

First thing to do is to declare the SOAP client. Class SoapClient will need the WSDL code dynamically generated by script cartoserver.wsdl.php.

<?php

$client = new SoapClient("http://url.to/server/cartoserver.wsdl.php"
                         . "?mapId=swiss_project.swiss");       
...

Method only needs map ID as argument.

try{
    $result = $client->getMapInfo("swiss_project.swiss");
    print_r($result);    
} catch (SoapFault $fault) {
    print $fault->faultstring;
}
            
?>

Result is shown below. It includes server configuration for the corresponding project and mapfile.

1.4.2. Getting a Map Using a Point and a Scale

The simpliest way to obtain a map from CartoWeb server is to send an X-Y location and a scale.

First thing to do is to declare the SOAP client. Class SoapClient will need the WSDL code dynamically generated by script cartoserver.wsdl.php.

<?php

$client = new SoapClient("http://url.to/server/cartoserver.wsdl.php"
                         . "?mapId=swiss_project.swiss");       
...

The map ID is required also in the request object.

$request->mapId = 'swiss_project.swiss';
...

In this example, only main map and scale bar are requested. So key map's isDrawn attribute is set to false.

$request->imagesRequest->className = 'ImagesRequest';

$request->imagesRequest->mainmap->isDrawn = true;
$request->imagesRequest->mainmap->path = '';
$request->imagesRequest->mainmap->width = 500;
$request->imagesRequest->mainmap->height = 500;
$request->imagesRequest->mainmap->format = '';

$request->imagesRequest->keymap->isDrawn = false;
$request->imagesRequest->keymap->path = '';
$request->imagesRequest->keymap->width = 0;
$request->imagesRequest->keymap->height = 0;
$request->imagesRequest->keymap->format = '';

$request->imagesRequest->scalebar->isDrawn = true;
$request->imagesRequest->scalebar->path = '';
$request->imagesRequest->scalebar->width = 100;
$request->imagesRequest->scalebar->height = 100;
$request->imagesRequest->scalebar->format = '';
...

Two layers are displayed. Resolution attribute is set to null to keep standard Mapserver resolution.

$request->layersRequest->className = 'LayersRequest';

$request->layersRequest->layerIds = array('swiss_layer_1',
                                          'swiss_layer_2');
$request->layersRequest->resolution = null;
...

In this case, the location request object is of type zoom-point, and zoom type is set to ZOOM_SCALE. Bbox is unused but is required.

$request->locationRequest->className = 'LocationRequest';

$request->locationRequest->locationType = 'zoomPointLocationRequest';
$request->locationRequest
        ->zoomPointLocationRequest->bbox->minx = 500000;
$request->locationRequest
        ->zoomPointLocationRequest->bbox->miny = 100000;
$request->locationRequest
        ->zoomPointLocationRequest->bbox->maxx = 600000;
$request->locationRequest
        ->zoomPointLocationRequest->bbox->maxy = 200000;
$request->locationRequest
        ->zoomPointLocationRequest->point->x = 550000;
$request->locationRequest
        ->zoomPointLocationRequest->point->y = 150000;
$request->locationRequest
        ->zoomPointLocationRequest->zoomType = 'ZOOM_SCALE';
$request->locationRequest
        ->zoomPointLocationRequest->scale = 200000;
...

Now request object is ready, SOAP method is called.

try{
    $result = $client->getMap($request);
    print_r($result);    
} catch (SoapFault $fault) {
    print $fault->faultstring;
}
            
?>

Result is shown below. It includes relative paths to generated images and new bounding box computed from requested scale.

stdClass Object
(
  [timestamp] => 1107925732
  [serverMessages] => Array
    (
    )
  [imagesResult] => stdClass Object
    (
      [className] => ImagesResult
      [mainmap] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110839565198671.jpg
          [width] => 500
          [height] => 500
          [format] => 
        )
      [keymap] => stdClass Object
        (
          [isDrawn] => 
          [path] => 
          [width] => 
          [height] => 
          [format] => 
        )
      [scalebar] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110839565198672.png
          [width] => 300
          [height] => 31
          [format] => 
        )
    )
  [locationResult] => stdClass Object
    (
      [className] => LocationResult
      [bbox] => stdClass Object
        (
          [minx] => 536770.840477
          [miny] => 136770.840477
          [maxx] => 563229.159523
          [maxy] => 163229.159523
        )
      [scale] => 200000
    )
)

1.4.3. Executing a Query

The following code shows how to use queries to display hilighted selection and to retrieve corresponding attributes.

First thing to do is to declare the SOAP client. Class SoapClient will need the WSDL code dynamically generated by script cartoserver.wsdl.php.

<?php

$client = new SoapClient("http://url.to/server/cartoserver.wsdl.php"
                         . "?mapId=swiss_project.swiss");       
...

The map ID is required also in the request object.

$request->mapId = 'swiss_project.swiss';
...

In this example, only main map and key map are requested. So scale bar's isDrawn attribute is set to false.

$request->imagesRequest->className = 'ImagesRequest';

$request->imagesRequest->mainmap->isDrawn = true;
$request->imagesRequest->mainmap->path = '';
$request->imagesRequest->mainmap->width = 500;
$request->imagesRequest->mainmap->height = 500;
$request->imagesRequest->mainmap->format = '';

$request->imagesRequest->keymap->isDrawn = true;
$request->imagesRequest->keymap->path = '';
$request->imagesRequest->keymap->width = 100;
$request->imagesRequest->keymap->height = 100;
$request->imagesRequest->keymap->format = '';

$request->imagesRequest->scalebar->isDrawn = false;
$request->imagesRequest->scalebar->path = '';
$request->imagesRequest->scalebar->width = 0;
$request->imagesRequest->scalebar->height = 0;
$request->imagesRequest->scalebar->format = '';
...

Two layers are displayed. Resolution attribute is set to null to keep standard Mapserver resolution.

$request->layersRequest->className = 'LayersRequest';

$request->layersRequest->layerIds = array('swiss_layer_1',
                                          'swiss_layer_2');
$request->layersRequest->resolution = null;
...

In this case, the location request object is of type bbox. Only new bounding box is required.

$request->locationRequest->className = 'LocationRequest';

$request->locationRequest->locationType = 'bboxLocationRequest';
$request->locationRequest->bboxLocationRequest->bbox->minx = 550000;
$request->locationRequest->bboxLocationRequest->bbox->miny = 100000;
$request->locationRequest->bboxLocationRequest->bbox->maxx = 600000;
$request->locationRequest->bboxLocationRequest->bbox->maxy = 150000;
...

The query will be performed on a rectangle, on all selected layers (ie. layers defined in layers request object). IDs and attributes will be returned.

$request->queryRequest->className = 'QueryRequest';

$request->queryRequest->shape->className = 'Bbox';
$request->queryRequest->shape->minx = 570000;
$request->queryRequest->shape->miny = 120000;
$request->queryRequest->shape->maxx = 580000;
$request->queryRequest->shape->maxy = 130000;
$request->queryRequest->queryAllLayers = true;
$request->queryRequest->defaultMaskMode = false;
$request->queryRequest->defaultTableFlags->returnAttributes = true;
$request->queryRequest->defaultTableFlags->returnTable = true;
$request->queryRequest->querySelections = array();
...

Now request object is ready, SOAP method is called.

try{
    $result = $client->getMap($request);
    print_r($result);    
} catch (SoapFault $fault) {
    print $fault->faultstring;
}
            
?>

Result is shown below. It includes relative paths to generated images and new scale computed from requested bounding box.

Query results include one table per layer. No results were found in layer swiss_layer_1 and two results in swiss_layer_2. As requested, attributes (here attribute_3 and attribute_4) are returned for each row.