Apache OpenOffice Wiki - User contributions [en]

Porting notes

2007-04-12T03:18:00Z

Jiao.jianhua: /* Common Objects to port */

=== Things to watch out for ===
* The mapping of the vba constants is different. Take for example the <tt>xlGuess</tt> constant, in VBA it's fully qualified name is <tt>Excel.XlYesNoGuess.xlGuess</tt>, in the helperapi it's <tt>com.sun.star.helper.constant.XlYesNoGuess.xlGuess</tt> and in oovbaapi it's <tt>org.openoffice.excel.XlYesNoGuess.xlGuess</tt>
* All objects in the helperapi extend [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/HelperInterfaceAdaptor.java?rev=1.1 HelperInterfaceAdaptor], nothing similar (yet) exists in oovbaapi so this can be ignored in the implementation
* There are a quite few helper classes in the helperapi project e.g. <tt>RangeHelper.java</tt> they shouldn't be confused with the actual implementation objects we wish to port.
* classes and idl files of the same name can exist in multiple namespaces and this can be confusing. Because the helperapi was written with both the word and excel api(s) in mind there can be classes that share a common implementation and interfaces e.g.
** <tt>com/sun/star/helper/calc/XShape.idl</tt>
** <tt>com/sun/star/helper/common/XShape.idl</tt>
** <tt>com/sun/star/helper/writer/XShape.idl</tt>
* Collections, these are handled differently see implementing a vba [[Porting notes#Collection|Collection]] in oovbaapi
* Every helperapi idl method defines [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/BasicErrorException.idl BasicErrorException] which allows and api method to transfer an error code and associated string paramater to basic.

=== Hints for porting idl ===
==== Objects with Default Properties ====
This is something not handled by the helperapi but something you should be aware of when implementing a vba compatibility object. What is a default property, an example probably explains the concept better.

Range("a1") = "text"

is a short cut for

Range("a1").Value = "text"

<tt>Value</tt> is a default property in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultProperty.idl XDefaultProperty.idl ]

==== Objects with Default Method ====

Similar to above some vba objects have a default method e.g. the <tt>Collection</tt> object

set col = Sheets
msgbox col(1).Name

is a short cut for

set col = Sheets
msgbox col.Item(1).Name

<tt>Item</tt> is a default method in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultMethod.idl XDefaultMethod.idl ]

==== Porting Collection objects ====
Generally all collection objects have a <tt>Count</tt> and an <tt>Item</tt> method and additionally the behaviour mentioned above. Also Collection objects can be used in a <tt>For Each</tt> loop. To cater for that a helper implementation object <tt>ScVbaCollectionBaseImpl</tt> provides the necessary information to the basic runtime to allow it to provide the classic vba <tt>Collection</tt> class syntax support. It also requires to be initialised by an XIndexAccess implementation. Additionally the class inheriting from <tt>ScVbaCollectionBaseImpl</tt> must provide the translation between the object iterated ( via XIndexAccess ) and the corrosponding compatibilty object returned to openoffice basic via the the <tt>createCollectionObject</tt> method.

A example of a ported <tt>Collection</tt> object can be found in the [[Porting example]] section

=== Calc Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by || Status || Notes
|-
| XAutoFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AutoFilterImpl.java AutoFilterImpl] || || || there is a partial (untested) implementation in the porting example section, would be nice for some one to finish
|-
| XFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FilterImpl.java FilterImpl.java] || || || see above.
|-
| XFilters.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FiltersImpl.java FiltersImpl.java] || || || see above.
|-
| XAxes.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxesImpl.java] || npower || in progress ||
|-
| XAxis.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxisImpl.java] || npower || in progress ||
|-
| XAxisTitle.idl || xxxx || || ||
|-
| XCalc.idl || xxxx || not required for porting see [[Application Object]] || || This is not a 'real' object but in a collection of global method/attributes that probably should be part of the XApplication.idl interface
|-
| XChartObject.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectImpl.java ChartObjectImpl.java] || npower || complete || not-tested
|-
| XChartObjects.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectsImpl.java ChartObjectsImpl.java] || npower || complete || not-tested
|-
| XChart.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartImpl.java ChartImpl.java] || npower || in progress ||
|-
| XCharts.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartsImpl.java ChartsImpl.java] || npower || in progress ||
|-
| XChartTitle.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartTileImpl.java ChartTitleImpl.java] || npower || complete || not-tested
|-
| XDataLabel.idl || xxxx || || ||
|-
| XDataLabels.idl || xxxx || || ||
|-
| XFormatCondition.idl || xxxx || || ||
|-
| XFormatConditions.idl || xxxx || || ||
|-
| XFormat.idl || xxxx || || ||
|-
| XHPageBreak.idl || xxxx || || ||
|-
| XHPageBreaks.idl || xxxx || || ||
|-
| XName.idl || xxxx || sola || ||
|-
| XNames.idl || xxxx || sola || ||
|-
| XPageBreak.idl || xxxx || || ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPageSetup.idl XPageSetup.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PageSetupImpl.java PageSetupImpl] || zhang ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPane.idl XPane.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PaneImpl.java PaneImpl] || Jiao.Jianhua || calc complete||
|-
| XPoint.idl || xxxx || ||
|-
| XPoints.idl || xxxx || ||
|-
| XProtection.idl || xxxx || ||
|-
| XQueryTable.idl || xxxx || ||
|-
| XQueryTables.idl || xxxx || ||
|-
| XShape.idl || xxxx || jiao.jianhua || in progress ||
|-
| XShapes.idl || xxxx || jiao.jianhua || calc complete, no full text ||
|-
| XStyle.idl || xxxx || ||
|-
| XStyles.idl || xxxx || ||
|-
| XTitle.idl || xxxx || ||
|-
| XVPageBreak.idl || xxxx || ||
|-
| XVPageBreaks.idl|| xxxx || ||
|}

=== Common Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by? || Status ||
|-
| XAutoFilter.idl || xxxx || ||
|-
| XPictureFormat || xxxx || Jiao.Jianhua || in progress
|-
| XColorFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XPosSize || xxxx || Jiao.Jianhua || implemented in org.openoffice.XControl ||
|-
| XWindow || xxxx || ||
|-
| XFileSearch || xxxx || ||
|-
| XWrapFormat || xxxx || || in word ||
|-
| XFillFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XShapeRange || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XFoundFiles || xxxx || ||
|-
| XLineFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XTextFrame || xxxx || Jiao.Jianhua || calc complete, no full text ||
|}

=== Missing attributes/methods to port ===
[[Application Object]]

Porting notes

2007-04-10T09:23:51Z

Jiao.jianhua: /* Common Objects to port */

=== Things to watch out for ===
* The mapping of the vba constants is different. Take for example the <tt>xlGuess</tt> constant, in VBA it's fully qualified name is <tt>Excel.XlYesNoGuess.xlGuess</tt>, in the helperapi it's <tt>com.sun.star.helper.constant.XlYesNoGuess.xlGuess</tt> and in oovbaapi it's <tt>org.openoffice.excel.XlYesNoGuess.xlGuess</tt>
* All objects in the helperapi extend [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/HelperInterfaceAdaptor.java?rev=1.1 HelperInterfaceAdaptor], nothing similar (yet) exists in oovbaapi so this can be ignored in the implementation
* There are a quite few helper classes in the helperapi project e.g. <tt>RangeHelper.java</tt> they shouldn't be confused with the actual implementation objects we wish to port.
* classes and idl files of the same name can exist in multiple namespaces and this can be confusing. Because the helperapi was written with both the word and excel api(s) in mind there can be classes that share a common implementation and interfaces e.g.
** <tt>com/sun/star/helper/calc/XShape.idl</tt>
** <tt>com/sun/star/helper/common/XShape.idl</tt>
** <tt>com/sun/star/helper/writer/XShape.idl</tt>
* Collections, these are handled differently see implementing a vba [[Porting notes#Collection|Collection]] in oovbaapi
* Every helperapi idl method defines [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/BasicErrorException.idl BasicErrorException] which allows and api method to transfer an error code and associated string paramater to basic.

=== Hints for porting idl ===
==== Objects with Default Properties ====
This is something not handled by the helperapi but something you should be aware of when implementing a vba compatibility object. What is a default property, an example probably explains the concept better.

Range("a1") = "text"

is a short cut for

Range("a1").Value = "text"

<tt>Value</tt> is a default property in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultProperty.idl XDefaultProperty.idl ]

==== Objects with Default Method ====

Similar to above some vba objects have a default method e.g. the <tt>Collection</tt> object

set col = Sheets
msgbox col(1).Name

is a short cut for

set col = Sheets
msgbox col.Item(1).Name

<tt>Item</tt> is a default method in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultMethod.idl XDefaultMethod.idl ]

==== Porting Collection objects ====
Generally all collection objects have a <tt>Count</tt> and an <tt>Item</tt> method and additionally the behaviour mentioned above. Also Collection objects can be used in a <tt>For Each</tt> loop. To cater for that a helper implementation object <tt>ScVbaCollectionBaseImpl</tt> provides the necessary information to the basic runtime to allow it to provide the classic vba <tt>Collection</tt> class syntax support. It also requires to be initialised by an XIndexAccess implementation. Additionally the class inheriting from <tt>ScVbaCollectionBaseImpl</tt> must provide the translation between the object iterated ( via XIndexAccess ) and the corrosponding compatibilty object returned to openoffice basic via the the <tt>createCollectionObject</tt> method.

A example of a ported <tt>Collection</tt> object can be found in the [[Porting example]] section

=== Calc Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by || Status || Notes
|-
| XAutoFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AutoFilterImpl.java AutoFilterImpl] || || || there is a partial (untested) implementation in the porting example section, would be nice for some one to finish
|-
| XFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FilterImpl.java FilterImpl.java] || || || see above.
|-
| XFilters.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FiltersImpl.java FiltersImpl.java] || || || see above.
|-
| XAxes.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxesImpl.java] || npower || in progress ||
|-
| XAxis.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxisImpl.java] || npower || in progress ||
|-
| XAxisTitle.idl || xxxx || || ||
|-
| XCalc.idl || xxxx || not required for porting see [[Application Object]] || || This is not a 'real' object but in a collection of global method/attributes that probably should be part of the XApplication.idl interface
|-
| XChartObject.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectImpl.java ChartObjectImpl.java] || npower || complete || not-tested
|-
| XChartObjects.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectsImpl.java ChartObjectsImpl.java] || npower || complete || not-tested
|-
| XChart.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartImpl.java ChartImpl.java] || npower || in progress ||
|-
| XCharts.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartsImpl.java ChartsImpl.java] || npower || in progress ||
|-
| XChartTitle.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartTileImpl.java ChartTitleImpl.java] || npower || complete || not-tested
|-
| XDataLabel.idl || xxxx || || ||
|-
| XDataLabels.idl || xxxx || || ||
|-
| XFormatCondition.idl || xxxx || || ||
|-
| XFormatConditions.idl || xxxx || || ||
|-
| XFormat.idl || xxxx || || ||
|-
| XHPageBreak.idl || xxxx || || ||
|-
| XHPageBreaks.idl || xxxx || || ||
|-
| XName.idl || xxxx || sola || ||
|-
| XNames.idl || xxxx || sola || ||
|-
| XPageBreak.idl || xxxx || || ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPageSetup.idl XPageSetup.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PageSetupImpl.java PageSetupImpl] || zhang ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPane.idl XPane.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PaneImpl.java PaneImpl] || Jiao.Jianhua || calc complete||
|-
| XPoint.idl || xxxx || ||
|-
| XPoints.idl || xxxx || ||
|-
| XProtection.idl || xxxx || ||
|-
| XQueryTable.idl || xxxx || ||
|-
| XQueryTables.idl || xxxx || ||
|-
| XShape.idl || xxxx || jiao.jianhua || in progress ||
|-
| XShapes.idl || xxxx || jiao.jianhua || calc complete, no full text ||
|-
| XStyle.idl || xxxx || ||
|-
| XStyles.idl || xxxx || ||
|-
| XTitle.idl || xxxx || ||
|-
| XVPageBreak.idl || xxxx || ||
|-
| XVPageBreaks.idl|| xxxx || ||
|}

=== Common Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by? || Status ||
|-
| XAutoFilter.idl || xxxx || ||
|-
| XPictureFormat || xxxx || Jiao.Jianhua || in progress
|-
| XColorFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XPosSize || xxxx || Jiao.Jianhua || implemented in org.openoffice.XControl ||
|-
| XWindow || xxxx || ||
|-
| XFileSearch || xxxx || ||
|-
| XWrapFormat || xxxx || ||
|-
| XFillFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XShapeRange || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XFoundFiles || xxxx || ||
|-
| XLineFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XTextFrame || xxxx || Jiao.Jianhua || calc complete, no full text ||
|}

=== Missing attributes/methods to port ===
[[Application Object]]

Porting notes

2007-04-10T09:23:25Z

Jiao.jianhua: /* Calc Objects to port */

=== Things to watch out for ===
* The mapping of the vba constants is different. Take for example the <tt>xlGuess</tt> constant, in VBA it's fully qualified name is <tt>Excel.XlYesNoGuess.xlGuess</tt>, in the helperapi it's <tt>com.sun.star.helper.constant.XlYesNoGuess.xlGuess</tt> and in oovbaapi it's <tt>org.openoffice.excel.XlYesNoGuess.xlGuess</tt>
* All objects in the helperapi extend [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/HelperInterfaceAdaptor.java?rev=1.1 HelperInterfaceAdaptor], nothing similar (yet) exists in oovbaapi so this can be ignored in the implementation
* There are a quite few helper classes in the helperapi project e.g. <tt>RangeHelper.java</tt> they shouldn't be confused with the actual implementation objects we wish to port.
* classes and idl files of the same name can exist in multiple namespaces and this can be confusing. Because the helperapi was written with both the word and excel api(s) in mind there can be classes that share a common implementation and interfaces e.g.
** <tt>com/sun/star/helper/calc/XShape.idl</tt>
** <tt>com/sun/star/helper/common/XShape.idl</tt>
** <tt>com/sun/star/helper/writer/XShape.idl</tt>
* Collections, these are handled differently see implementing a vba [[Porting notes#Collection|Collection]] in oovbaapi
* Every helperapi idl method defines [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/BasicErrorException.idl BasicErrorException] which allows and api method to transfer an error code and associated string paramater to basic.

=== Hints for porting idl ===
==== Objects with Default Properties ====
This is something not handled by the helperapi but something you should be aware of when implementing a vba compatibility object. What is a default property, an example probably explains the concept better.

Range("a1") = "text"

is a short cut for

Range("a1").Value = "text"

<tt>Value</tt> is a default property in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultProperty.idl XDefaultProperty.idl ]

==== Objects with Default Method ====

Similar to above some vba objects have a default method e.g. the <tt>Collection</tt> object

set col = Sheets
msgbox col(1).Name

is a short cut for

set col = Sheets
msgbox col.Item(1).Name

<tt>Item</tt> is a default method in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultMethod.idl XDefaultMethod.idl ]

==== Porting Collection objects ====
Generally all collection objects have a <tt>Count</tt> and an <tt>Item</tt> method and additionally the behaviour mentioned above. Also Collection objects can be used in a <tt>For Each</tt> loop. To cater for that a helper implementation object <tt>ScVbaCollectionBaseImpl</tt> provides the necessary information to the basic runtime to allow it to provide the classic vba <tt>Collection</tt> class syntax support. It also requires to be initialised by an XIndexAccess implementation. Additionally the class inheriting from <tt>ScVbaCollectionBaseImpl</tt> must provide the translation between the object iterated ( via XIndexAccess ) and the corrosponding compatibilty object returned to openoffice basic via the the <tt>createCollectionObject</tt> method.

A example of a ported <tt>Collection</tt> object can be found in the [[Porting example]] section

=== Calc Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by || Status || Notes
|-
| XAutoFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AutoFilterImpl.java AutoFilterImpl] || || || there is a partial (untested) implementation in the porting example section, would be nice for some one to finish
|-
| XFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FilterImpl.java FilterImpl.java] || || || see above.
|-
| XFilters.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FiltersImpl.java FiltersImpl.java] || || || see above.
|-
| XAxes.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxesImpl.java] || npower || in progress ||
|-
| XAxis.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxisImpl.java] || npower || in progress ||
|-
| XAxisTitle.idl || xxxx || || ||
|-
| XCalc.idl || xxxx || not required for porting see [[Application Object]] || || This is not a 'real' object but in a collection of global method/attributes that probably should be part of the XApplication.idl interface
|-
| XChartObject.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectImpl.java ChartObjectImpl.java] || npower || complete || not-tested
|-
| XChartObjects.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectsImpl.java ChartObjectsImpl.java] || npower || complete || not-tested
|-
| XChart.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartImpl.java ChartImpl.java] || npower || in progress ||
|-
| XCharts.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartsImpl.java ChartsImpl.java] || npower || in progress ||
|-
| XChartTitle.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartTileImpl.java ChartTitleImpl.java] || npower || complete || not-tested
|-
| XDataLabel.idl || xxxx || || ||
|-
| XDataLabels.idl || xxxx || || ||
|-
| XFormatCondition.idl || xxxx || || ||
|-
| XFormatConditions.idl || xxxx || || ||
|-
| XFormat.idl || xxxx || || ||
|-
| XHPageBreak.idl || xxxx || || ||
|-
| XHPageBreaks.idl || xxxx || || ||
|-
| XName.idl || xxxx || sola || ||
|-
| XNames.idl || xxxx || sola || ||
|-
| XPageBreak.idl || xxxx || || ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPageSetup.idl XPageSetup.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PageSetupImpl.java PageSetupImpl] || zhang ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPane.idl XPane.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PaneImpl.java PaneImpl] || Jiao.Jianhua || calc complete||
|-
| XPoint.idl || xxxx || ||
|-
| XPoints.idl || xxxx || ||
|-
| XProtection.idl || xxxx || ||
|-
| XQueryTable.idl || xxxx || ||
|-
| XQueryTables.idl || xxxx || ||
|-
| XShape.idl || xxxx || jiao.jianhua || in progress ||
|-
| XShapes.idl || xxxx || jiao.jianhua || calc complete, no full text ||
|-
| XStyle.idl || xxxx || ||
|-
| XStyles.idl || xxxx || ||
|-
| XTitle.idl || xxxx || ||
|-
| XVPageBreak.idl || xxxx || ||
|-
| XVPageBreaks.idl|| xxxx || ||
|}

=== Common Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by? || Status ||
|-
| XAutoFilter.idl || xxxx || ||
|-
| XPictureFormat || xxxx || Jiao.Jianhu || in progress
|-
| XColorFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XPosSize || xxxx || Jiao.Jianhua || implemented in org.openoffice.XControl ||
|-
| XWindow || xxxx || ||
|-
| XFileSearch || xxxx || ||
|-
| XWrapFormat || xxxx || ||
|-
| XFillFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XShapeRange || xxxx || Jiao.Jianhu || calc complete, no full text ||
|-
| XFoundFiles || xxxx || ||
|-
| XLineFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XTextFrame || xxxx || Jiao.Jianhua || calc complete, no full text ||
|}

=== Missing attributes/methods to port ===
[[Application Object]]

Porting notes

2007-04-10T09:22:18Z

Jiao.jianhua: /* Common Objects to port */

=== Things to watch out for ===
* The mapping of the vba constants is different. Take for example the <tt>xlGuess</tt> constant, in VBA it's fully qualified name is <tt>Excel.XlYesNoGuess.xlGuess</tt>, in the helperapi it's <tt>com.sun.star.helper.constant.XlYesNoGuess.xlGuess</tt> and in oovbaapi it's <tt>org.openoffice.excel.XlYesNoGuess.xlGuess</tt>
* All objects in the helperapi extend [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/HelperInterfaceAdaptor.java?rev=1.1 HelperInterfaceAdaptor], nothing similar (yet) exists in oovbaapi so this can be ignored in the implementation
* There are a quite few helper classes in the helperapi project e.g. <tt>RangeHelper.java</tt> they shouldn't be confused with the actual implementation objects we wish to port.
* classes and idl files of the same name can exist in multiple namespaces and this can be confusing. Because the helperapi was written with both the word and excel api(s) in mind there can be classes that share a common implementation and interfaces e.g.
** <tt>com/sun/star/helper/calc/XShape.idl</tt>
** <tt>com/sun/star/helper/common/XShape.idl</tt>
** <tt>com/sun/star/helper/writer/XShape.idl</tt>
* Collections, these are handled differently see implementing a vba [[Porting notes#Collection|Collection]] in oovbaapi
* Every helperapi idl method defines [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/BasicErrorException.idl BasicErrorException] which allows and api method to transfer an error code and associated string paramater to basic.

=== Hints for porting idl ===
==== Objects with Default Properties ====
This is something not handled by the helperapi but something you should be aware of when implementing a vba compatibility object. What is a default property, an example probably explains the concept better.

Range("a1") = "text"

is a short cut for

Range("a1").Value = "text"

<tt>Value</tt> is a default property in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultProperty.idl XDefaultProperty.idl ]

==== Objects with Default Method ====

Similar to above some vba objects have a default method e.g. the <tt>Collection</tt> object

set col = Sheets
msgbox col(1).Name

is a short cut for

set col = Sheets
msgbox col.Item(1).Name

<tt>Item</tt> is a default method in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultMethod.idl XDefaultMethod.idl ]

==== Porting Collection objects ====
Generally all collection objects have a <tt>Count</tt> and an <tt>Item</tt> method and additionally the behaviour mentioned above. Also Collection objects can be used in a <tt>For Each</tt> loop. To cater for that a helper implementation object <tt>ScVbaCollectionBaseImpl</tt> provides the necessary information to the basic runtime to allow it to provide the classic vba <tt>Collection</tt> class syntax support. It also requires to be initialised by an XIndexAccess implementation. Additionally the class inheriting from <tt>ScVbaCollectionBaseImpl</tt> must provide the translation between the object iterated ( via XIndexAccess ) and the corrosponding compatibilty object returned to openoffice basic via the the <tt>createCollectionObject</tt> method.

A example of a ported <tt>Collection</tt> object can be found in the [[Porting example]] section

=== Calc Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by || Status || Notes
|-
| XAutoFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AutoFilterImpl.java AutoFilterImpl] || || || there is a partial (untested) implementation in the porting example section, would be nice for some one to finish
|-
| XFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FilterImpl.java FilterImpl.java] || || || see above.
|-
| XFilters.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FiltersImpl.java FiltersImpl.java] || || || see above.
|-
| XAxes.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxesImpl.java] || npower || in progress ||
|-
| XAxis.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxisImpl.java] || npower || in progress ||
|-
| XAxisTitle.idl || xxxx || || ||
|-
| XCalc.idl || xxxx || not required for porting see [[Application Object]] || || This is not a 'real' object but in a collection of global method/attributes that probably should be part of the XApplication.idl interface
|-
| XChartObject.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectImpl.java ChartObjectImpl.java] || npower || complete || not-tested
|-
| XChartObjects.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectsImpl.java ChartObjectsImpl.java] || npower || complete || not-tested
|-
| XChart.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartImpl.java ChartImpl.java] || npower || in progress ||
|-
| XCharts.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartsImpl.java ChartsImpl.java] || npower || in progress ||
|-
| XChartTitle.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartTileImpl.java ChartTitleImpl.java] || npower || complete || not-tested
|-
| XDataLabel.idl || xxxx || || ||
|-
| XDataLabels.idl || xxxx || || ||
|-
| XFormatCondition.idl || xxxx || || ||
|-
| XFormatConditions.idl || xxxx || || ||
|-
| XFormat.idl || xxxx || || ||
|-
| XHPageBreak.idl || xxxx || || ||
|-
| XHPageBreaks.idl || xxxx || || ||
|-
| XName.idl || xxxx || sola || ||
|-
| XNames.idl || xxxx || sola || ||
|-
| XPageBreak.idl || xxxx || || ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPageSetup.idl XPageSetup.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PageSetupImpl.java PageSetupImpl] || zhang ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPane.idl XPane.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PaneImpl.java PaneImpl] || Jiao.Jianhua || calc complete||
|-
| XPoint.idl || xxxx || ||
|-
| XPoints.idl || xxxx || ||
|-
| XProtection.idl || xxxx || ||
|-
| XQueryTable.idl || xxxx || ||
|-
| XQueryTables.idl || xxxx || ||
|-
| XShape.idl || xxxx || jiao.jianhua ||
|-
| XShapes.idl || xxxx || jiao.jianhua || in progress ||
|-
| XStyle.idl || xxxx || ||
|-
| XStyles.idl || xxxx || ||
|-
| XTitle.idl || xxxx || ||
|-
| XVPageBreak.idl || xxxx || ||
|-
| XVPageBreaks.idl|| xxxx || ||
|}

=== Common Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by? || Status ||
|-
| XAutoFilter.idl || xxxx || ||
|-
| XPictureFormat || xxxx || Jiao.Jianhu || in progress
|-
| XColorFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XPosSize || xxxx || Jiao.Jianhua || implemented in org.openoffice.XControl ||
|-
| XWindow || xxxx || ||
|-
| XFileSearch || xxxx || ||
|-
| XWrapFormat || xxxx || ||
|-
| XFillFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XShapeRange || xxxx || Jiao.Jianhu || calc complete, no full text ||
|-
| XFoundFiles || xxxx || ||
|-
| XLineFormat || xxxx || Jiao.Jianhua || calc complete, no full text ||
|-
| XTextFrame || xxxx || Jiao.Jianhua || calc complete, no full text ||
|}

=== Missing attributes/methods to port ===
[[Application Object]]

Porting notes

2007-04-10T09:20:39Z

Jiao.jianhua: /* Common Objects to port */

=== Things to watch out for ===
* The mapping of the vba constants is different. Take for example the <tt>xlGuess</tt> constant, in VBA it's fully qualified name is <tt>Excel.XlYesNoGuess.xlGuess</tt>, in the helperapi it's <tt>com.sun.star.helper.constant.XlYesNoGuess.xlGuess</tt> and in oovbaapi it's <tt>org.openoffice.excel.XlYesNoGuess.xlGuess</tt>
* All objects in the helperapi extend [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/HelperInterfaceAdaptor.java?rev=1.1 HelperInterfaceAdaptor], nothing similar (yet) exists in oovbaapi so this can be ignored in the implementation
* There are a quite few helper classes in the helperapi project e.g. <tt>RangeHelper.java</tt> they shouldn't be confused with the actual implementation objects we wish to port.
* classes and idl files of the same name can exist in multiple namespaces and this can be confusing. Because the helperapi was written with both the word and excel api(s) in mind there can be classes that share a common implementation and interfaces e.g.
** <tt>com/sun/star/helper/calc/XShape.idl</tt>
** <tt>com/sun/star/helper/common/XShape.idl</tt>
** <tt>com/sun/star/helper/writer/XShape.idl</tt>
* Collections, these are handled differently see implementing a vba [[Porting notes#Collection|Collection]] in oovbaapi
* Every helperapi idl method defines [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/BasicErrorException.idl BasicErrorException] which allows and api method to transfer an error code and associated string paramater to basic.

=== Hints for porting idl ===
==== Objects with Default Properties ====
This is something not handled by the helperapi but something you should be aware of when implementing a vba compatibility object. What is a default property, an example probably explains the concept better.

Range("a1") = "text"

is a short cut for

Range("a1").Value = "text"

<tt>Value</tt> is a default property in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultProperty.idl XDefaultProperty.idl ]

==== Objects with Default Method ====

Similar to above some vba objects have a default method e.g. the <tt>Collection</tt> object

set col = Sheets
msgbox col(1).Name

is a short cut for

set col = Sheets
msgbox col.Item(1).Name

<tt>Item</tt> is a default method in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultMethod.idl XDefaultMethod.idl ]

==== Porting Collection objects ====
Generally all collection objects have a <tt>Count</tt> and an <tt>Item</tt> method and additionally the behaviour mentioned above. Also Collection objects can be used in a <tt>For Each</tt> loop. To cater for that a helper implementation object <tt>ScVbaCollectionBaseImpl</tt> provides the necessary information to the basic runtime to allow it to provide the classic vba <tt>Collection</tt> class syntax support. It also requires to be initialised by an XIndexAccess implementation. Additionally the class inheriting from <tt>ScVbaCollectionBaseImpl</tt> must provide the translation between the object iterated ( via XIndexAccess ) and the corrosponding compatibilty object returned to openoffice basic via the the <tt>createCollectionObject</tt> method.

A example of a ported <tt>Collection</tt> object can be found in the [[Porting example]] section

=== Calc Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by || Status || Notes
|-
| XAutoFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AutoFilterImpl.java AutoFilterImpl] || || || there is a partial (untested) implementation in the porting example section, would be nice for some one to finish
|-
| XFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FilterImpl.java FilterImpl.java] || || || see above.
|-
| XFilters.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FiltersImpl.java FiltersImpl.java] || || || see above.
|-
| XAxes.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxesImpl.java] || npower || in progress ||
|-
| XAxis.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AxesImpl.java AxisImpl.java] || npower || in progress ||
|-
| XAxisTitle.idl || xxxx || || ||
|-
| XCalc.idl || xxxx || not required for porting see [[Application Object]] || || This is not a 'real' object but in a collection of global method/attributes that probably should be part of the XApplication.idl interface
|-
| XChartObject.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectImpl.java ChartObjectImpl.java] || npower || complete || not-tested
|-
| XChartObjects.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectsImpl.java ChartObjectsImpl.java] || npower || complete || not-tested
|-
| XChart.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartImpl.java ChartImpl.java] || npower || in progress ||
|-
| XCharts.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartsImpl.java ChartsImpl.java] || npower || in progress ||
|-
| XChartTitle.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartTileImpl.java ChartTitleImpl.java] || npower || complete || not-tested
|-
| XDataLabel.idl || xxxx || || ||
|-
| XDataLabels.idl || xxxx || || ||
|-
| XFormatCondition.idl || xxxx || || ||
|-
| XFormatConditions.idl || xxxx || || ||
|-
| XFormat.idl || xxxx || || ||
|-
| XHPageBreak.idl || xxxx || || ||
|-
| XHPageBreaks.idl || xxxx || || ||
|-
| XName.idl || xxxx || sola || ||
|-
| XNames.idl || xxxx || sola || ||
|-
| XPageBreak.idl || xxxx || || ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPageSetup.idl XPageSetup.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PageSetupImpl.java PageSetupImpl] || zhang ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPane.idl XPane.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PaneImpl.java PaneImpl] || Jiao.Jianhua || calc complete||
|-
| XPoint.idl || xxxx || ||
|-
| XPoints.idl || xxxx || ||
|-
| XProtection.idl || xxxx || ||
|-
| XQueryTable.idl || xxxx || ||
|-
| XQueryTables.idl || xxxx || ||
|-
| XShape.idl || xxxx || jiao.jianhua ||
|-
| XShapes.idl || xxxx || jiao.jianhua || in progress ||
|-
| XStyle.idl || xxxx || ||
|-
| XStyles.idl || xxxx || ||
|-
| XTitle.idl || xxxx || ||
|-
| XVPageBreak.idl || xxxx || ||
|-
| XVPageBreaks.idl|| xxxx || ||
|}

=== Common Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by? || Status ||
|-
| XAutoFilter.idl || xxxx || ||
|-
| XPictureFormat || xxxx || Jiao.Jianhu ||
|-
| XColorFormat || xxxx || ||
|-
| XPosSize || xxxx || Jiao.Jianhua || implemented in org.openoffice.XControl ||
|-
| XWindow || xxxx || ||
|-
| XFileSearch || xxxx || ||
|-
| XWrapFormat || xxxx || ||
|-
| XFillFormat || xxxx || Jiao.Jianhua ||
|-
| XShapeRange || xxxx || Jiao.Jianhu ||
|-
| XFoundFiles || xxxx || ||
|-
| XLineFormat || xxxx || Jiao.Jianhua ||
|-
| XTextFrame || xxxx || jiao.jianhua ||
|}

=== Missing attributes/methods to port ===
[[Application Object]]

Porting notes

2007-03-26T02:57:00Z

Jiao.jianhua: /* Calc Objects to port */

=== Things to watch out for ===
* The mapping of the vba constants is different. Take for example the <tt>xlGuess</tt> constant, in VBA it's fully qualified name is <tt>Excel.XlYesNoGuess.xlGuess</tt>, in the helperapi it's <tt>com.sun.star.helper.constant.XlYesNoGuess.xlGuess</tt> and in oovbaapi it's <tt>org.openoffice.excel.XlYesNoGuess.xlGuess</tt>
* All objects in the helperapi extend [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/HelperInterfaceAdaptor.java?rev=1.1 HelperInterfaceAdaptor], nothing similar (yet) exists in oovbaapi so this can be ignored in the implementation
* There are a quite few helper classes in the helperapi project e.g. <tt>RangeHelper.java</tt> they shouldn't be confused with the actual implementation objects we wish to port.
* classes and idl files of the same name can exist in multiple namespaces and this can be confusing. Because the helperapi was written with both the word and excel api(s) in mind there can be classes that share a common implementation and interfaces e.g.
** <tt>com/sun/star/helper/calc/XShape.idl</tt>
** <tt>com/sun/star/helper/common/XShape.idl</tt>
** <tt>com/sun/star/helper/writer/XShape.idl</tt>
* Collections, these are handled differently see implementing a vba [[Porting notes#Collection|Collection]] in oovbaapi
* Every helperapi idl method defines [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/BasicErrorException.idl BasicErrorException] which allows and api method to transfer an error code and associated string paramater to basic.

=== Hints for porting idl ===
==== Objects with Default Properties ====
This is something not handled by the helperapi but something you should be aware of when implementing a vba compatibility object. What is a default property, an example probably explains the concept better.

Range("a1") = "text"

is a short cut for

Range("a1").Value = "text"

<tt>Value</tt> is a default property in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultProperty.idl XDefaultProperty.idl ]

==== Objects with Default Method ====

Similar to above some vba objects have a default method e.g. the <tt>Collection</tt> object

set col = Sheets
msgbox col(1).Name

is a short cut for

set col = Sheets
msgbox col.Item(1).Name

<tt>Item</tt> is a default method in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultMethod.idl XDefaultMethod.idl ]

==== Porting Collection objects ====
Generally all collection objects have a <tt>Count</tt> and an <tt>Item</tt> method and additionally the behaviour mentioned above. Also Collection objects can be used in a <tt>For Each</tt> loop. To cater for that a helper implementation object <tt>ScVbaCollectionBaseImpl</tt> provides the necessary information to the basic runtime to allow it to provide the classic vba <tt>Collection</tt> class syntax support. It also requires to be initialised by an XIndexAccess implementation. Additionally the class inheriting from <tt>ScVbaCollectionBaseImpl</tt> must provide the translation between the object iterated ( via XIndexAccess ) and the corrosponding compatibilty object returned to openoffice basic via the the <tt>createCollectionObject</tt> method.

A example of a ported <tt>Collection</tt> object can be found in the [[Porting example]] section

=== Calc Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by || Status || Notes
|-
| XAutoFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AutoFilterImpl.java AutoFilterImpl] || || || there is a partial (untested) implementation in the porting example section, would be nice for some one to finish
|-
| XFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FilterImpl.java FilterImpl.java] || || || see above.
|-
| XFilters.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FiltersImpl.java FiltersImpl.java] || || || see above.
|-
| XAxes.idl || xxxx || || ||
|-
| XAxis.idl || xxxx || || ||
|-
| XAxisTitle.idl || xxxx || || ||
|-
| XCalc.idl || xxxx || not required for porting see [[Application Object]] || || This is not a 'real' object but in a collection of global method/attributes that probably should be part of the XApplication.idl interface
|-
| XChartObject.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectImpl.java ChartObjectImpl.java] || npower || in progress ||
|-
| XChartObjects.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectsImpl.java ChartObjectsImpl.java] || npower || in progress ||
|-
| XChart.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartImpl.java ChartImpl.java] || npower || in progress ||
|-
| XCharts.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartsImpl.java ChartsImpl.java] || npower || in progress ||
|-
| XChartTitle.idl || xxxx || || ||
|-
| XDataLabel.idl || xxxx || || ||
|-
| XDataLabels.idl || xxxx || || ||
|-
| XFormatCondition.idl || xxxx || || ||
|-
| XFormatConditions.idl || xxxx || || ||
|-
| XFormat.idl || xxxx || || ||
|-
| XHPageBreak.idl || xxxx || || ||
|-
| XHPageBreaks.idl || xxxx || || ||
|-
| XName.idl || xxxx || sola || ||
|-
| XNames.idl || xxxx || sola || ||
|-
| XPageBreak.idl || xxxx || || ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPageSetup.idl XPageSetup.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PageSetupImpl.java PageSetupImpl] || zhang ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPane.idl XPane.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PaneImpl.java PaneImpl] || Jiao.Jianhua || calc complete||
|-
| XPoint.idl || xxxx || ||
|-
| XPoints.idl || xxxx || ||
|-
| XProtection.idl || xxxx || ||
|-
| XQueryTable.idl || xxxx || ||
|-
| XQueryTables.idl || xxxx || ||
|-
| XShape.idl || xxxx || jiao.jianhua ||
|-
| XShapes.idl || xxxx || jiao.jianhua || in progress ||
|-
| XStyle.idl || xxxx || ||
|-
| XStyles.idl || xxxx || ||
|-
| XTitle.idl || xxxx || ||
|-
| XVPageBreak.idl || xxxx || ||
|-
| XVPageBreaks.idl|| xxxx || ||
|}

=== Common Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by? || Status ||
|-
| XAutoFilter.idl || xxxx || ||
|-
| XPictureFormat || xxxx || ||
|-
| XColorFormat || xxxx || ||
|-
| XPosSize || xxxx || Jiao.Jianhua || implemented in org.openoffice.XControl ||
|-
| XWindow || xxxx || ||
|-
| XFileSearch || xxxx || ||
|-
| XWrapFormat || xxxx || ||
|-
| XFillFormat || xxxx || ||
|-
| XShapeRange || xxxx || ||
|-
| XFoundFiles || xxxx || ||
|-
| XLineFormat || xxxx || ||
|-
| XTextFrame || xxxx || jiao.jianhua ||
|}

=== Missing attributes/methods to port ===
[[Application Object]]

Porting notes

2007-03-23T03:53:23Z

Jiao.jianhua: /* Common Objects to port */

=== Things to watch out for ===
* The mapping of the vba constants is different. Take for example the <tt>xlGuess</tt> constant, in VBA it's fully qualified name is <tt>Excel.XlYesNoGuess.xlGuess</tt>, in the helperapi it's <tt>com.sun.star.helper.constant.XlYesNoGuess.xlGuess</tt> and in oovbaapi it's <tt>org.openoffice.excel.XlYesNoGuess.xlGuess</tt>
* All objects in the helperapi extend [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/HelperInterfaceAdaptor.java?rev=1.1 HelperInterfaceAdaptor], nothing similar (yet) exists in oovbaapi so this can be ignored in the implementation
* There are a quite few helper classes in the helperapi project e.g. <tt>RangeHelper.java</tt> they shouldn't be confused with the actual implementation objects we wish to port.
* classes and idl files of the same name can exist in multiple namespaces and this can be confusing. Because the helperapi was written with both the word and excel api(s) in mind there can be classes that share a common implementation and interfaces e.g.
** <tt>com/sun/star/helper/calc/XShape.idl</tt>
** <tt>com/sun/star/helper/common/XShape.idl</tt>
** <tt>com/sun/star/helper/writer/XShape.idl</tt>
* Collections, these are handled differently see implementing a vba [[Porting notes#Collection|Collection]] in oovbaapi
* Every helperapi idl method defines [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/BasicErrorException.idl BasicErrorException] which allows and api method to transfer an error code and associated string paramater to basic.

=== Hints for porting idl ===
==== Objects with Default Properties ====
This is something not handled by the helperapi but something you should be aware of when implementing a vba compatibility object. What is a default property, an example probably explains the concept better.

Range("a1") = "text"

is a short cut for

Range("a1").Value = "text"

<tt>Value</tt> is a default property in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultProperty.idl XDefaultProperty.idl ]

==== Objects with Default Method ====

Similar to above some vba objects have a default method e.g. the <tt>Collection</tt> object

set col = Sheets
msgbox col(1).Name

is a short cut for

set col = Sheets
msgbox col.Item(1).Name

<tt>Item</tt> is a default method in the example above. We can provide similar behavior in basic with a compatibility api object ensuring the object implements [http://api.openoffice.org/source/browse/*checkout*/api/udkapi/com/sun/star/script/XDefaultMethod.idl XDefaultMethod.idl ]

==== Porting Collection objects ====
Generally all collection objects have a <tt>Count</tt> and an <tt>Item</tt> method and additionally the behaviour mentioned above. Also Collection objects can be used in a <tt>For Each</tt> loop. To cater for that a helper implementation object <tt>ScVbaCollectionBaseImpl</tt> provides the necessary information to the basic runtime to allow it to provide the classic vba <tt>Collection</tt> class syntax support. It also requires to be initialised by an XIndexAccess implementation. Additionally the class inheriting from <tt>ScVbaCollectionBaseImpl</tt> must provide the translation between the object iterated ( via XIndexAccess ) and the corrosponding compatibilty object returned to openoffice basic via the the <tt>createCollectionObject</tt> method.

A example of a ported <tt>Collection</tt> object can be found in the [[Porting example]] section

=== Calc Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by || Status || Notes
|-
| XAutoFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/AutoFilterImpl.java AutoFilterImpl] || || || there is a partial (untested) implementation in the porting example section, would be nice for some one to finish
|-
| XFilter.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FilterImpl.java FilterImpl.java] || || || see above.
|-
| XFilters.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/FiltersImpl.java FiltersImpl.java] || || || see above.
|-
| XAxes.idl || xxxx || || ||
|-
| XAxis.idl || xxxx || || ||
|-
| XAxisTitle.idl || xxxx || || ||
|-
| XCalc.idl || xxxx || not required for porting see [[Application Object]] || || This is not a 'real' object but in a collection of global method/attributes that probably should be part of the XApplication.idl interface
|-
| XChartObject.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectImpl.java ChartObjectImpl.java] || npower || in progress ||
|-
| XChartObjects.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartObjectsImpl.java ChartObjectsImpl.java] || npower || in progress ||
|-
| XChart.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartImpl.java ChartImpl.java] || npower || in progress ||
|-
| XCharts.idl || [http://api.openoffice.org/source/browse/*checkout*/api/helperapi/impl/com/sun/star/helper/calc/ChartsImpl.java ChartsImpl.java] || npower || in progress ||
|-
| XChartTitle.idl || xxxx || || ||
|-
| XDataLabel.idl || xxxx || || ||
|-
| XDataLabels.idl || xxxx || || ||
|-
| XFormatCondition.idl || xxxx || || ||
|-
| XFormatConditions.idl || xxxx || || ||
|-
| XFormat.idl || xxxx || || ||
|-
| XHPageBreak.idl || xxxx || || ||
|-
| XHPageBreaks.idl || xxxx || || ||
|-
| XName.idl || xxxx || sola || ||
|-
| XNames.idl || xxxx || sola || ||
|-
| XPageBreak.idl || xxxx || || ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPageSetup.idl XPageSetup.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PageSetupImpl.java PageSetupImpl] || zhang ||
|-
|[http://api.openoffice.org/source/browse/api/helperapi/com/sun/star/helper/calc/XPane.idl XPane.idl] || [http://api.openoffice.org/source/browse/api/helperapi/impl/com/sun/star/helper/calc/PaneImpl.java PaneImpl] || Jiao.Jianhua || calc complete||
|-
| XPoint.idl || xxxx || ||
|-
| XPoints.idl || xxxx || ||
|-
| XProtection.idl || xxxx || ||
|-
| XQueryTable.idl || xxxx || ||
|-
| XQueryTables.idl || xxxx || ||
|-
| XShape.idl || xxxx || jiao.jianhua ||
|-
| XShapes.idl || xxxx || ||
|-
| XStyle.idl || xxxx || ||
|-
| XStyles.idl || xxxx || ||
|-
| XTitle.idl || xxxx || ||
|-
| XVPageBreak.idl || xxxx || ||
|-
| XVPageBreaks.idl|| xxxx || ||
|}

=== Common Objects to port ===
{| style="vertical-align:top; text-align:left; background-color:#efefef;"
|- style="background-color:#d6d6d6;font-weight:bold;"
| Object || helperapi implementation name || Porting stared by? || Status ||
|-
| XAutoFilter.idl || xxxx || ||
|-
| XPictureFormat || xxxx || ||
|-
| XColorFormat || xxxx || ||
|-
| XPosSize || xxxx || Jiao.Jianhua || implemented in org.openoffice.XControl ||
|-
| XWindow || xxxx || ||
|-
| XFileSearch || xxxx || ||
|-
| XWrapFormat || xxxx || ||
|-
| XFillFormat || xxxx || ||
|-
| XShapeRange || xxxx || ||
|-
| XFoundFiles || xxxx || ||
|-
| XLineFormat || xxxx || ||
|-
| XTextFrame || xxxx || jiao.jianhua ||
|}

=== Missing attributes/methods to port ===
[[Application Object]]

IDL Files and Cpp zh

2007-03-21T10:04:18Z

Jiao.jianhua: /* 一个具体的例子 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

对于这两个服务，还有其他的问题。如果这是从表格得到一个com.sun.star.table.CellRange，那么它就只是一个CellRange。但是，如果是从电子表格得到的，那么它就不只是一个CellRange，而是个真实的com.sun.star.sheet.SheetCellRange。 SheetCellRange只是CellRange的扩展版。而这两个服务通过对一个表格或者电子表格调用getCellRangeByName()得到。

有时，特别对字处理，对某些API方法的调用，只有通过开发手册才能准确知道返回了哪些基础服务。这点对字处理特别严重。但是，通常来说，当你知道你有什么服务，那就可以通过API文档准确推断出查询哪些接口是有效的。不需要猜测，这是科学的方法。

== 一个具体的例子 ==

对SDK，这些IDL文件可以在 <OpenOffice.org1.1_SDK>/idl/目录找到。当然，有个问题就是，这些SDK中的UNO IDL文件和二进制的OpenOffice.org库是有些区别的。这是因为SDK通常是在新版的OpenOffice.org发布后几个月才出现（现在不是这样）。然而，对于这个改变，我们将会在介绍另外一种方法：注册表浏览（registry exploring）后给予解释。事实上，此刻我并不清楚通过注册表可以得到什么样的信息。(具体请参考 [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

我们现在来看一个例子：我们首先来看::com::sun::star::document::OfficeDocument，查看<OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl（下面呈现的，并且去除了所有注释）：
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
在[[IDL_Files_and_Cpp_zh#IDL_.E8.AF.A6.E8.BF.B0|这个章节]]，我们已经涉及了接口。
[http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png 开发手册图标]更明确的表示了这个结构。如果我们需要查看::com::sun::star::text::TextDocument，请参考<OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl。
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
可以看到，TextDocument服务和OfficeDocument服务都在这里。

现在，我们深入这个例子，并且增加注释。为了这个目的，我们使用以前处理过的代码。(请查看[[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T09:59:54Z

Jiao.jianhua: /* 一个具体的例子 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

对于这两个服务，还有其他的问题。如果这是从表格得到一个com.sun.star.table.CellRange，那么它就只是一个CellRange。但是，如果是从电子表格得到的，那么它就不只是一个CellRange，而是个真实的com.sun.star.sheet.SheetCellRange。 SheetCellRange只是CellRange的扩展版。而这两个服务通过对一个表格或者电子表格调用getCellRangeByName()得到。

有时，特别对字处理，对某些API方法的调用，只有通过开发手册才能准确知道返回了哪些基础服务。这点对字处理特别严重。但是，通常来说，当你知道你有什么服务，那就可以通过API文档准确推断出查询哪些接口是有效的。不需要猜测，这是科学的方法。

== 一个具体的例子 ==

对SDK，这些IDL文件可以在 <OpenOffice.org1.1_SDK>/idl/目录找到。当然，有个问题就是，这些SDK中的UNO IDL文件和二进制的OpenOffice.org库是有些区别的。这是因为SDK通常是在新版的OpenOffice.org发布后几个月才出现（现在不是这样）。然而，对于这个改变，我们将会在介绍另外一种方法：注册表浏览（registry exploring）后给予解释。事实上，此刻我并不清楚通过注册表可以得到什么样的信息。(具体请参考 [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

我们现在来看一个例子：我们首先来看::com::sun::star::document::OfficeDocument，查看<OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl（下面呈现的，并且去除了所有注释）：
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
在[[IDL_Files_and_Cpp_zh#IDL_.E8.AF.A6.E8.BF.B0|这个章节]]，我们已经涉及了接口。
[http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png 开发手册图标]更明确的表示了这个结构。如果我们需要查看::com::sun::star::text::TextDocument，请参考<OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl。
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T09:54:54Z

Jiao.jianhua: /* 一个具体的例子 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

对于这两个服务，还有其他的问题。如果这是从表格得到一个com.sun.star.table.CellRange，那么它就只是一个CellRange。但是，如果是从电子表格得到的，那么它就不只是一个CellRange，而是个真实的com.sun.star.sheet.SheetCellRange。 SheetCellRange只是CellRange的扩展版。而这两个服务通过对一个表格或者电子表格调用getCellRangeByName()得到。

有时，特别对字处理，对某些API方法的调用，只有通过开发手册才能准确知道返回了哪些基础服务。这点对字处理特别严重。但是，通常来说，当你知道你有什么服务，那就可以通过API文档准确推断出查询哪些接口是有效的。不需要猜测，这是科学的方法。

== 一个具体的例子 ==

对SDK，这些IDL文件可以在 <OpenOffice.org1.1_SDK>/idl/目录找到。当然，有个问题就是，这些SDK中的UNO IDL文件和二进制的OpenOffice.org库是有些区别的。这是因为SDK通常是在新版的OpenOffice.org发布后几个月才出现（现在不是这样）。然而，对于这个改变，我们将会在介绍另外一种方法：注册表浏览（registry exploring）后给予解释。事实上，此刻我并不清楚通过注册表可以得到什么样的信息。(具体请参考 [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

我们现在来看一个例子：我们首先来看::com::sun::star::document::OfficeDocument，查看<OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl（下面呈现的，并且去除了所有注释）：
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
在[[IDL_Files_and_Cpp_zh#IDL_.E8.AF.A6.E8.BF.B0|这个章节]]，我们已经提及了接口。
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T09:51:24Z

Jiao.jianhua: /* 一个具体的例子 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

对于这两个服务，还有其他的问题。如果这是从表格得到一个com.sun.star.table.CellRange，那么它就只是一个CellRange。但是，如果是从电子表格得到的，那么它就不只是一个CellRange，而是个真实的com.sun.star.sheet.SheetCellRange。 SheetCellRange只是CellRange的扩展版。而这两个服务通过对一个表格或者电子表格调用getCellRangeByName()得到。

有时，特别对字处理，对某些API方法的调用，只有通过开发手册才能准确知道返回了哪些基础服务。这点对字处理特别严重。但是，通常来说，当你知道你有什么服务，那就可以通过API文档准确推断出查询哪些接口是有效的。不需要猜测，这是科学的方法。

== 一个具体的例子 ==

对SDK，这些IDL文件可以在 <OpenOffice.org1.1_SDK>/idl/目录找到。当然，有个问题就是，这些SDK中的UNO IDL文件和二进制的OpenOffice.org库是有些区别的。这是因为SDK通常是在新版的OpenOffice.org发布后几个月才出现（现在不是这样）。然而，对于这个改变，我们将会在介绍另外一种方法：注册表浏览（registry exploring）后给予解释。事实上，此刻我并不清楚通过注册表可以得到什么样的信息。(具体请参考 [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

我们现在来看一个例子：我们首先来看::com::sun::star::document::OfficeDocument，查看<OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl（下面呈现的，并且去除了所有注释）：
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T09:49:25Z

Jiao.jianhua: /* 一个具体的例子 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

对于这两个服务，还有其他的问题。如果这是从表格得到一个com.sun.star.table.CellRange，那么它就只是一个CellRange。但是，如果是从电子表格得到的，那么它就不只是一个CellRange，而是个真实的com.sun.star.sheet.SheetCellRange。 SheetCellRange只是CellRange的扩展版。而这两个服务通过对一个表格或者电子表格调用getCellRangeByName()得到。

有时，特别对字处理，对某些API方法的调用，只有通过开发手册才能准确知道返回了哪些基础服务。这点对字处理特别严重。但是，通常来说，当你知道你有什么服务，那就可以通过API文档准确推断出查询哪些接口是有效的。不需要猜测，这是科学的方法。

== 一个具体的例子 ==

对SDK，这些IDL文件可以在 <OpenOffice.org1.1_SDK>/idl/目录找到。当然，有个问题就是，这些SDK中的UNO IDL文件和二进制的OpenOffice.org库是有些区别的。这是因为SDK通常是在新版的OpenOffice.org发布后几个月才出现（现在不是这样）。然而，对于这个改变，我们将会在介绍另外一种方法：注册表浏览（registry exploring）后给予解释。事实上，此刻我并不清楚通过注册表可以得到什么样的信息。(具体请参考 [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

我们现在来看一个例子：我们首先来看::com::sun::star::document::OfficeDocument，查看<OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl（下面呈现的，并且去除了所有的注释）：
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T09:45:36Z

Jiao.jianhua: /* 一个具体的例子 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

对于这两个服务，还有其他的问题。如果这是从表格得到一个com.sun.star.table.CellRange，那么它就只是一个CellRange。但是，如果是从电子表格得到的，那么它就不只是一个CellRange，而是个真实的com.sun.star.sheet.SheetCellRange。 SheetCellRange只是CellRange的扩展版。而这两个服务通过对一个表格或者电子表格调用getCellRangeByName()得到。

有时，特别对字处理，对某些API方法的调用，只有通过开发手册才能准确知道返回了哪些基础服务。这点对字处理特别严重。但是，通常来说，当你知道你有什么服务，那就可以通过API文档准确推断出查询哪些接口是有效的。不需要猜测，这是科学的方法。

== 一个具体的例子 ==

对SDK，这些IDL文件可以在 <OpenOffice.org1.1_SDK>/idl/目录找到。当然，有个问题就是，这些SDK中的UNO IDL文件和二进制的OpenOffice.org库是有些区别的。这是因为SDK通常是在新版的OpenOffice.org发布后几个月才出现（现在不是这样）。然而，对于这个改变，我们将会在介绍另外一种方法：注册表浏览（registry exploring）后给予解释。事实上，此刻我并不清楚通过注册表可以得到什么样的信息。(具体请参考 [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T09:10:27Z

Jiao.jianhua: /* A concrete Example */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

对于这两个服务，还有其他的问题。如果这是从表格得到一个com.sun.star.table.CellRange，那么它就只是一个CellRange。但是，如果是从电子表格得到的，那么它就不只是一个CellRange，而是个真实的com.sun.star.sheet.SheetCellRange。 SheetCellRange只是CellRange的扩展版。而这两个服务通过对一个表格或者电子表格调用getCellRangeByName()得到。

有时，特别对字处理，对某些API方法的调用，只有通过开发手册才能准确知道返回了哪些基础服务。这点对字处理特别严重。但是，通常来说，当你知道你有什么服务，那就可以通过API文档准确推断出查询哪些接口是有效的。不需要猜测，这是科学的方法。

== 一个具体的例子 ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T09:09:51Z

Jiao.jianhua: /* Danny Brewer 的观点 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

对于这两个服务，还有其他的问题。如果这是从表格得到一个com.sun.star.table.CellRange，那么它就只是一个CellRange。但是，如果是从电子表格得到的，那么它就不只是一个CellRange，而是个真实的com.sun.star.sheet.SheetCellRange。 SheetCellRange只是CellRange的扩展版。而这两个服务通过对一个表格或者电子表格调用getCellRangeByName()得到。

有时，特别对字处理，对某些API方法的调用，只有通过开发手册才能准确知道返回了哪些基础服务。这点对字处理特别严重。但是，通常来说，当你知道你有什么服务，那就可以通过API文档准确推断出查询哪些接口是有效的。不需要猜测，这是科学的方法。

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T08:59:11Z

Jiao.jianhua: /* Danny Brewer 的观点 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

对于这两个服务，还有其他的问题。如果这是从表格得到一个com.sun.star.table.CellRange，那么它就只是一个CellRange。但是，如果是从电子表格得到的，那么它就不只是一个CellRange，而是个真实的com.sun.star.sheet.SheetCellRange。 SheetCellRange只是CellRange的扩展版。而这两个服务通过对一个表格或者电子表格调用getCellRangeByName()得到。

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T08:47:40Z

Jiao.jianhua: /* Danny Brewer 的观点 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么知道是什么服务可用了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T08:46:22Z

Jiao.jianhua: /* Danny Brewer 的观点 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么，我就知道是什么服务了，因为我给出了服务的名字。

如果你知道服务的名字，那么就通常知道什么接口是可用的－－通过查看API文档，不需要猜测，不需要Xray工具，这绝对科学。这些可用接口的集合就是，服务本身的接口和这个服务包含的所有服务，并对这个概念递归使用的到的所有接口。

在下来的案例中，都很明确的知道拥有什么服务。

如果你可以调用getCellRangeByName()，那么你就有个SheetCellRange服务。如果可以调用getCellByPosition()，那么就只有SheetCell可以使用。对于SheetCell和SheetCellRange，有许多相同的内容可用，但是，他们却是不同的东西。 SheetCellRange指的是一个矩形区域内单元格的集合，而SheetCell只表示一个单元格。有些操作，对一个单元格可以，但把单元格集合在一起就不可以对之操作。

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T07:59:08Z

Jiao.jianhua: /* Danny Brewer 的观点 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

对上面的讨论，如果使用TextDocument取代SpreadsheetDocument。
那么怎么知道什么是基础的服务呢？

这里没有捷径，通常的方法就是观察。如果你装载了一个电子表格，那么你就有了SpreadsheetDocument服务。

相同的，如果通过服务的名称创建一个对象，例如：
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
那么，我就知道是什么服务了，因为我给出了服务的名字。

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-21T07:50:13Z

Jiao.jianhua: /* Danny Brewer 的观点 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
因此，对服务SpreadsheetDocument－一个电子表格文档，就集合了接口XSpreadsheetDocument和服务OfficeDocument中的接口。所以，尽管loadComponentFromURL返回的是一些接口，但是这些接口的都是基于一个基础的服务，这个服务就是SpreadsheetDocument。参考API文档，你就可以知道查询（query）哪些接口是有效的。
SpreadsheetDocument有服务（？）XSpreadsheetDocument。
OfficeDocument拥有服务（？）XPrintable和XStorable.
因为SpreadsheetDocument包含OfficeDocument，所以从SpreadsheetDocument查询接口XPrintable或者XStorable都是有效的。

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-20T07:50:58Z

Jiao.jianhua: /* Danny Brewer 的观点 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多服务
#更多接口
当然，对（1）来说，服务中的服务也同样意味着这些原始服务包含更多的接口。
让我来看一个不同的例子。
SpreadsheetDocument是一个服务。
SpreadsheetDocument包括服务OfficeDocument。对应的IDL文件如下：
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-20T07:46:06Z

Jiao.jianhua: /* Danny Brewer 的观点 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

然而，在API文档中，理解“服务”的概念是非常重要的。服务是聚合一下内容的唯一方法：
#更多的服务
#更多的接口
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T10:09:15Z

Jiao.jianhua: /* 通过IDL文件获取UNO信息 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer]] 的观点 ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T10:05:37Z

Jiao.jianhua: /* 通过IDL文件获取UNO信息 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。但是我们还是重复一下Danny Brewer's在OOoForum的观点。

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T10:03:42Z

Jiao.jianhua: /* 通过IDL文件获取UNO信息 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic 不能精确的表现方法和属性。

另一方法就是使用[http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

在前面的章节我们已经提供了相应的例子（特别[[Programming_OooWriter|programming OOoWriter in C++]]）。相信读者已经有了这方面的经验。 We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:47:40Z

Jiao.jianhua: /* 通过IDL文件获取UNO信息 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(访问 [http://www.ooomacros.org/dev.php#101416 这里]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:46:39Z

Jiao.jianhua: /* Gathering UNO information with IDL files */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= 通过IDL文件获取UNO信息 =
有多种方法可以获的UNO内的信息。

一个方法是使用OOoBasic和Bernard Marcelly的Xray工具(available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:39:56Z

Jiao.jianhua: /* 深入IDL */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在文档 [[Working_with_Shapes|shapes]] 中就会碰到属性处理。

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:39:27Z

Jiao.jianhua: /* 深入IDL */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 在[[Working_with_Shapes|shapes]]中就会碰到属性处理。

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:37:23Z

Jiao.jianhua: /* 深入IDL */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
服务的继承，将在下个章节进行介绍。

在OOo对象的术语中，特性和属性是有些区别的。而仅有的区别就是访问的方法不同。属性使用set/getPropertyValue(PropertyName,Any)访问，然而，特性是通过set/get(AttributeName)方法。. 我们在We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:31:38Z

Jiao.jianhua: /* 深入IDL */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们通常会在这个文档（[[Counter_Example#IDL_File|the counter example]]）中遇到。

接口可以衍生自基接口。一个衍生接口可以声明自身的特性和方法。但是，在衍生的接口中，特性和方法不能被重定义。
一个继承接口的例子：
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
也可以多重继承：
<pre>
// IDL
interface dog : animal, friend {
</pre>
对于服务的继承，将在下个章节进行介绍。

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:23:53Z

Jiao.jianhua: /* 深入IDL */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

方法可以有参数。参数列表中的每个参数必须以方向标志（direction flags）开始，也就是在一个知名的类型和参数标识符之前，必须有[in],[out]或者[inout]。下面给出的例子我们会经常在这个文档[[Counter_Example#IDL_File|the counter example]]中遇到：

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:11:21Z

Jiao.jianhua: /* Further with IDL */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== 深入IDL ==
IDL类型 :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:07:54Z

Jiao.jianhua: /* 描述一个模块 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:07:33Z

Jiao.jianhua: /* Specifying a module */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== 描述一个模块 ==
下来，对这个IDL描述，我们仍然使用相同的例子。
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>

== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:05:03Z

Jiao.jianhua: /* 简介 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以公开（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:04:00Z

Jiao.jianhua: /* IDL 详述 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以导出（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义接口的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T09:03:03Z

Jiao.jianhua: /* Specifying a service */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以导出（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义解的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==描述一个服务==
继续使用上面的例子，下面就是对应的IDL描述。
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// 公开的接口:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
在这里，我们看到一个float的类型。其它的IDL类型会在后面逐步引入。

== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T08:59:40Z

Jiao.jianhua: /* Specifying an interface */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以导出（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义解的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==描述一个接口==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T08:58:20Z

Jiao.jianhua: /* Specifying an interface */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以导出（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义解的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==Specifying an interface==
我们选择的例子，接口XdrivingDirection (不包括在OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>

==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T08:57:20Z

Jiao.jianhua: /* IDL 详述 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以导出（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义解的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。

开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T08:56:56Z

Jiao.jianhua: /* IDL 详述 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以导出（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
接口使用接口定义语言（IDL）描述。UNO使用UNO-IDL作为其接口定义语言。IDL是描述性语言（不是编程语言），用来描述对象实现的接口。通过IDL，你可以定义解的名字和每个特性、方法的名字等等。如果你创建了IDL文件，就可以使用IDL编译器创建C++头文件。
开始的例子，我们只是使用IDL直接描述一些简单的模块（modules）。

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T08:37:44Z

Jiao.jianhua: /* IDL specification */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以导出（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL 详述 =
Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language.
The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T08:33:41Z

Jiao.jianhua: /* 简介 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

服务类似Java对象。

1. 服务可以继承其他服务或者什么都不继承。（每个服务都递归的遵循这个规则。）

2. 服务可以含有（include）其他的服务或者什么都不包含。（每个服务都递归的遵循这个规则。）

3. 服务可以导出（实现）接口。

4. 服务拥有属性。

5. 接口可以继承其他的接口或者什么也不继承。（每个接口都递归的遵循这个规则。）

6. 接口可以含有（include）其他的接口或者什么都不包含。（每个接口都递归的遵循这个规则。）

7. 接口能够执行/实现（implement）方法。

8. 接口名称通常有一个大写X。

通过这些规则，就可以推断，方法通常（ALWAYS）在接口中，而属性通常在服务中。

另请参阅[[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]]和 [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL specification =
Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language.
The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T08:16:10Z

Jiao.jianhua: /* 简介 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法 getPropertyValue 和 setPropertyValue。” 这个定义也恰好区分了特性和属性的含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer]]的规则'''

Services are similar to objects in java.

1. A service can inherit from zero or one other service. (which each service can recursively follow these rules.)

2. A service can include zero or more services. (which each service can recursively follow these rules.)

3. A service can export (implement) interfaces.

4. A service can have properties.

5. An interface can inherit from zero or one other interface. (which each interface can recursively follow these rules.)

6. An interface can include from zero or more interfaces. (which each interface can recursively apply these rules.)

7. An interface can implement methods.

8. An interface is always named with an X.

From these rules you can deduce that methods are ALWAYS found in interfaces, and properties are ALWAYS found in services.

See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL specification =
Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language.
The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T08:12:40Z

Jiao.jianhua: /* 简介 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法getPropertyValue和setPropertyValue。” 这个定义也恰好区分了特性和属性含义。服务是属性的集合，接口是方法的集合，而这些方法则提供了改变属性的途径（means）。

'''[[CppSDKAuthors|Danny Brewer's]] rules'''

Services are similar to objects in java.

1. A service can inherit from zero or one other service. (which each service can recursively follow these rules.)

2. A service can include zero or more services. (which each service can recursively follow these rules.)

3. A service can export (implement) interfaces.

4. A service can have properties.

5. An interface can inherit from zero or one other interface. (which each interface can recursively follow these rules.)

6. An interface can include from zero or more interfaces. (which each interface can recursively apply these rules.)

7. An interface can implement methods.

8. An interface is always named with an X.

From these rules you can deduce that methods are ALWAYS found in interfaces, and properties are ALWAYS found in services.

See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL specification =
Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language.
The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T08:07:46Z

Jiao.jianhua: /* 简介 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
对于 OpenOffice API, 服务是一个抽象的概念，它提供了一些特定的接口和特性/属性（properties/attributes）。就像开发手册（Developer's Guide）中所说：“属性是对象（an object）的数据。对象的通用接口（generic interface）可以使用属性的名字来实现对属性的访问，这些接口包括方法getPropertyValue和setPropertyValue。” 这个定义也恰好区分了特性和属性含义。服务 A service has a collection of properties and an interface is a collection of methods that provide a means to change properties.

'''[[CppSDKAuthors|Danny Brewer's]] rules'''

Services are similar to objects in java.

1. A service can inherit from zero or one other service. (which each service can recursively follow these rules.)

2. A service can include zero or more services. (which each service can recursively follow these rules.)

3. A service can export (implement) interfaces.

4. A service can have properties.

5. An interface can inherit from zero or one other interface. (which each interface can recursively follow these rules.)

6. An interface can include from zero or more interfaces. (which each interface can recursively apply these rules.)

7. An interface can implement methods.

8. An interface is always named with an X.

From these rules you can deduce that methods are ALWAYS found in interfaces, and properties are ALWAYS found in services.

See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL specification =
Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language.
The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T04:29:16Z

Jiao.jianhua: /* 简介 */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
参考 [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2].
In OpenOffice API, a "service" is an abstract concept providing certain interfaces and properties/attributes. As Developer's Guide states : “Properties are data in an object that are provided by name over a generic interface for property access, that contains getPropertyValue() and setPropertyValue() access methods.”. It would be better to distinguish between attribute and property. A service has a collection of properties and an interface is a collection of methods that provide a means to change properties.

'''[[CppSDKAuthors|Danny Brewer's]] rules'''

Services are similar to objects in java.

1. A service can inherit from zero or one other service. (which each service can recursively follow these rules.)

2. A service can include zero or more services. (which each service can recursively follow these rules.)

3. A service can export (implement) interfaces.

4. A service can have properties.

5. An interface can inherit from zero or one other interface. (which each interface can recursively follow these rules.)

6. An interface can include from zero or more interfaces. (which each interface can recursively apply these rules.)

7. An interface can implement methods.

8. An interface is always named with an X.

From these rules you can deduce that methods are ALWAYS found in interfaces, and properties are ALWAYS found in services.

See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL specification =
Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language.
The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T04:27:22Z

Jiao.jianhua: /* Introduction */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== 简介 ==
See [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2]
In OpenOffice API, a "service" is an abstract concept providing certain interfaces and properties/attributes. As Developer's Guide states : “Properties are data in an object that are provided by name over a generic interface for property access, that contains getPropertyValue() and setPropertyValue() access methods.”. It would be better to distinguish between attribute and property. A service has a collection of properties and an interface is a collection of methods that provide a means to change properties.

'''[[CppSDKAuthors|Danny Brewer's]] rules'''

Services are similar to objects in java.

1. A service can inherit from zero or one other service. (which each service can recursively follow these rules.)

2. A service can include zero or more services. (which each service can recursively follow these rules.)

3. A service can export (implement) interfaces.

4. A service can have properties.

5. An interface can inherit from zero or one other interface. (which each interface can recursively follow these rules.)

6. An interface can include from zero or more interfaces. (which each interface can recursively apply these rules.)

7. An interface can implement methods.

8. An interface is always named with an X.

From these rules you can deduce that methods are ALWAYS found in interfaces, and properties are ALWAYS found in services.

See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL specification =
Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language.
The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

IDL Files and Cpp zh

2007-03-16T04:25:01Z

Jiao.jianhua: /* Services and Interfaces */

[http://wiki.services.openoffice.org/wiki/IDL_Files_and_Cpp en]

介绍性的文章，请参阅[http://udk.openoffice.org/cpp/man/component_tutorial.html component tutorial].

= 服务（Services）和接口（Interfaces） =
== Introduction ==
See [http://api.openoffice.org/basic/man/tutorial/tutorial.pdf tutorial (in pdf) chapter 2]
In OpenOffice API, a "service" is an abstract concept providing certain interfaces and properties/attributes. As Developer's Guide states : “Properties are data in an object that are provided by name over a generic interface for property access, that contains getPropertyValue() and setPropertyValue() access methods.”. It would be better to distinguish between attribute and property. A service has a collection of properties and an interface is a collection of methods that provide a means to change properties.

'''[[CppSDKAuthors|Danny Brewer's]] rules'''

Services are similar to objects in java.

1. A service can inherit from zero or one other service. (which each service can recursively follow these rules.)

2. A service can include zero or more services. (which each service can recursively follow these rules.)

3. A service can export (implement) interfaces.

4. A service can have properties.

5. An interface can inherit from zero or one other interface. (which each interface can recursively follow these rules.)

6. An interface can include from zero or more interfaces. (which each interface can recursively apply these rules.)

7. An interface can implement methods.

8. An interface is always named with an X.

From these rules you can deduce that methods are ALWAYS found in interfaces, and properties are ALWAYS found in services.

See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= IDL specification =
Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language.
The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

==Specifying an interface==
We choose as an example, the interface XdrivingDirection (not in OOo):
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
</pre>
==Specifying a service==
Example above is still used, here is the corresponding IDL specification :
<pre>
// IDL
interface XdrivingDirection
{
void turnLeft();
void turnRight();
};
interface XaccelerationControl
{
void speedUp();
void slowDown();
};
service car
{
// exported interfaces:
interface XdrivingDirection;
interface XaccelerationControl;
[attribute] float speed;
[attribute] float angle;
};
</pre>
We see a float type and we would use other IDL types later.
== Specifying a module ==
Now, the same example would give this IDL specification :
<pre>
// IDL
module my_module
{
interface Xsomething
{
void methodone();
};
service my_service1
{
// exported interfaces:
interface Xsomething;
};
interface XsomethingElse
{
void methodTwo();
void methodThree();
};
service my_service2
{
// exported interfaces:
interface XsomethingElse;
};
};
</pre>
== Further with IDL ==
The IDL's types are :
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<TR VALIGN=TOP>
<TD WIDTH=12%>
char 

</TD>
<TD WIDTH=38%>
16-bit unicode character type 

</TD>
<TD WIDTH=12%>
boolean 

</TD>
<TD WIDTH=38%>
boolean type; true and false
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
byte 

</TD>
<TD WIDTH=38%>
8-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
short 

</TD>
<TD WIDTH=38%>
signed 16-bit ordinal integer type 

</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned short 

</TD>
<TD WIDTH=38%>
unsigned 16-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
long 

</TD>
<TD WIDTH=38%>
signed 32-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned long
</TD>
<TD WIDTH=38%>
unsigned 32-bit integer type 

</TD>
<TD WIDTH=12%>
hyper 

</TD>
<TD WIDTH=38%>
signed 64-bit ordinal integer type
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
unsigned hyper
</TD>
<TD WIDTH=38%>
unsigned 64-bit ordinal integer type 

</TD>
<TD WIDTH=12%>
float 

</TD>
<TD WIDTH=38%>
processor dependent float
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
double
</TD>
<TD WIDTH=38%>
processor dependent double 


</TD>
<TD WIDTH=12%>
string
</TD>
<TD WIDTH=38%>
string of 16-bit unicode characters
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=12%>
any
</TD>
<TD WIDTH=38%>
universal type, takes every fundamental
or compound UNO type, similar to Variant in other environments or
Object in Java
</TD>
<TD WIDTH=12%>

void 

</TD>
<TD WIDTH=38%>
Indicates that a method does not
provide a return value
</TD>
</TR>
</TABLE>

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : [[Counter_Example#IDL_File|the counter example]]

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface.
An example of interface inheritance :
<pre>
//IDL
interface animal {
attribute long age;
};
interface dog : animal {
attribute short leg;
}
</pre>
Multiple inheritance is also possible :
<pre>
// IDL
interface dog : animal, friend {
</pre>
Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining [[Working_with_Shapes|shapes]].

= Gathering UNO information with IDL files =
There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available [http://www.ooomacros.org/dev.php#101416 here]). '''Problem''' : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : [http://api.openoffice.org/docs/common/ref/index-files/index-1.html General OOoWEB Index]

We have provided examples in previous chapters (particularly [[Programming_OooWriter|programming OOoWriter in C++]]) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

== [[CppSDKAuthors|Danny Brewer 's]] Point of View ==

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....
# more services
# interfaces
The (1) more services part, of course, means that there are even more interfaces available at the original service.
Let me give a different example.
SpreadsheetDocument is a service.
SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :
<pre>
//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
//-------------------------------------------------------------------------

/** common service for all types of documents.
*/
service com::sun::star::document::OfficeDocument;

..........

//-------------------------------------------------------------------------

/** provides access to the collection of spreadsheets.
*/
interface com::sun::star::sheet::XSpreadsheetDocument;

//-------------------------------------------------------------------------
</pre>
Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document.
So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query.
SpreadsheetDocument has service XSpreadsheetDocument.
OfficeDocument has service XPrintable and XStorable.
Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument.
How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name.....
oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" )
then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

== A concrete Example ==

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Of course, the problem with this way is we only see the SDK's UNO IDL documentation, which can be slightly different from the Openoffice.org binary : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]])

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :
<pre>
//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
interface com::sun::star::frame::XModel;
interface com::sun::star::util::XModifiable;
interface com::sun::star::frame::XStorable;
interface com::sun::star::view::XPrintable;
[optional] interface XEventBroadcaster;
[optional] interface XEventsSupplier;
[optional] interface XDocumentInfoSupplier;
[optional] interface XViewDataSupplier;
[optional] interface com::sun::star::view::XPrintJobBroadcaster;
[property, optional] boolean AutomaticControlFocus;
[property, optional] boolean ApplyFormDesignMode;
};
</pre>
Remember we have already tackled Interfaces in [[IDL_Files_and_Cpp#IDL_specification|this section]].
This is shown with the [http://api.openoffice.org/docs/DevelopersGuide/FirstSteps/TextDocumentWithMethods.png Developper's Guide Figure]. If we now examine the
::com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl
<pre>
service TextDocument
{
service com::sun::star::document::OfficeDocument;
interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
....
};
</pre>
As can be seen TextDocument service and OfficeDocument service are together.

It's time to go deeper in our example and provide code with comments. For this purpose, we shall take code already tackled (see [[Programming_OooWriter#The_XTextCursor_Interface|the Corresponding Writer Code]]).
<code>[cpp]
//Listing 9 Writer Example
//C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);

Reference< XComponent > xWriterComponent =
rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
</code>

xWriterComponent gives us TextDocument service and then OfficeDocument service as already said. XTextDocument is an Interface of TextDocument service. XTextDocument.idl shows us the getText method but we don't know what new services are available. Only two ways to know that : Internet [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText interface]gives the answer : the service is com.sun.star.text.Text. The other way is to use Reflection as described later in [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces|this section]].
<code>[cpp]
//Listing 10 Writer Example (continuation)
//C++
Reference< XText > xText = xTextDocument->getText();
</code>
We try to get a XTextCursor Interface
<code>[cpp]
//Listing 11 Writer Example (continuation)
//C++
Reference< XTextCursor> xTextCursor = xText->createTextCursor();
</code>
But how to explain this code ? Looking in XText.idl files only shows two methods :
<pre>
//Listing 12 XText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XText: com::sun::star::text::XSimpleText
{
void insertTextContent( [in] com::sun::star::text::XTextRange xRange,
[in] com::sun::star::text::XTextContent xContent,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );
void removeTextContent( [in] com::sun::star::text::XTextContent xContent )
raises( com::sun::star::container::NoSuchElementException );

};
}; }; }; };
</pre>
But if you have a closer look at the IDL file, you will see the inheritance from XSimpleText. Is the createTextCursor method here ? Yes, as you can see.
<pre>
//Listing 13 XSimpleText Interface IDL file
// IDL
module com { module sun { module star { module text {
interface XSimpleText: com::sun::star::text::XTextRange
{
com::sun::star::text::XTextCursor createTextCursor();
com::sun::star::text::XTextCursor createTextCursorByRange( [in] com::sun::star::text::XTextRange aTextPosition );
[oneway] void insertString( [in] com::sun::star::text::XTextRange xRange,
[in] string aString,
[in] boolean bAbsorb );
void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
[in] short nControlCharacter,
[in] boolean bAbsorb )
raises( com::sun::star::lang::IllegalArgumentException );

};
}; }; }; };
</pre>
What are the services available here ? I have found them with a reflection tool :
<pre>
******** Services : 8
com.sun.star.text.TextSortable
com.sun.star.style.ParagraphPropertiesComplex
com.sun.star.style.ParagraphPropertiesAsian
com.sun.star.style.ParagraphProperties
com.sun.star.style.CharacterPropertiesComplex
com.sun.star.style.CharacterPropertiesAsian
com.sun.star.style.CharacterProperties
com.sun.star.text.TextCursor
</pre>
You can probably find all of them with internet but I think it will be a long task : a good reason for explaining reflection services later in this chapter.

Yes you have to walk through such ways to find what you can do when programming. Fortunately there is a shorter way : the SDK examples. Most of them are in Java but I have found many ideas with them.

= IDL and C++ =
This problem is tackled in [http://api.openoffice.org/docs/DevelopersGuide/ProfUNO/ProfUNO.htm#1+4+2+UNO+C%2B%2B+Binding Developer's guide]

== Getting an interface in C++ ==
In C++, you only have variables of an Interface type.
One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "[[SDKCppLanguage|SDK C++ language]]" and many other in [[UNO_automation_with_a_binary_%28executable%29|Office UNO automation]]. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like:
<code>[cpp]
//Listing 2 C++ code to get a service
//C++
Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service();
</code>
or
<code>[cpp]
Listing 3 using namespace to simplify the code
//C++
using namespace com::sun::star::document;
....
Reference<officeDocument> OfDoc = something_to_get_this_service();
</code>
and we want to query the XStorable interface to save our document. Three steps are involved in this query :
# Add your code's line as UNO's query
<code>[cpp]
//Listing 4 The UNO query in C++ code
// C++
// query from com::sun::star::frame::XStorable interface
Reference< XStorable > oToStore (OfDoc, UNO_QUERY);
</code>
# Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :
<code>[cpp]
//Listing 5 The corresponding include statement
//C++
#include <com/sun/star/frame/XStorable.hpp>
</code>
and the corresponding namespace statement is :
<code>[cpp]
//Listing 6 The corresponding namespace statement
//C++
using namespace com::sun::star::frame;
</code>
#Add the corresponding type in the makefile as shown below in red :
<pre>
# makefile
# added com.sun.star.frame.XStorable
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.uno.XAggregation \
com.sun.star.frame.XStorable \
com.sun.star.lang.XMain \
...
com.sun.star.container.XHierarchicalNameAccess
</pre>
Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4.

You have to learn to get interface in an other way.

==Getting an Interface through XMultiServiceFactory==

We have already encountered such a thing, so it should be quite familiar to us by now. But, because we have not discussed every step in detail, I want to illustrate how it works.

The previous section only deals with getting interfaces directely available because the corresponding service is available. For instance the code below deals with only one arrow of the Figure below and getting a Xmodel inteface starting from XtextDocument is a simple UNO_QUERY call (last line of the listing).
<code>[cpp]
//Listing 19 Simple UNO_QUERY call
// C++
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/Documents/demo.sxw"),sDocUrl);
Reference< XComponent > xWriterComponent = rComponentLoader->loadComponentFromURL(
sDocUrl,
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());

Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);
// Don't forget to include #include <com/sun/star/frame/XModel.hpp>
Reference < XModel > xModel (xTextDocument,UNO_QUERY);
</code>

[[Image:SimpleUNOQUERY.png|center]]

But how can you get an interface if the corresponding service is not directly available ?

'''First case :''' a method of your interface allows to get the new interface. It was the case of the code of Listing 11. In this case the corresponding hdl file is not necessary and I have not found a way to retrieve the new services available witout a reflection tool !

'''Second case :''' no interface's method can help you. You have to query a service before getting the interface. This can be done with two or three instructions style. I have already used both styles. Have a look into this listing :

<code>[cpp]
//Listing 20 Getting an Interface with XMultiServiceFacory
// C++
Reference < XTextDocument > xTextDocument (xWriterComponent,UNO_QUERY);

Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference <XTextTable> xTable (oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable")),UNO_QUERY);
</code>

which uses two instruction style. With three instructions style, the same code is shown in the listing above :

<code>[cpp]
//Listing 21 Inserting a Table in a OOoWriter Document
// C++
Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);

Reference< XInterface > textTable = oDocMSF->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
// Don't forget to add #include <com/sun/star/text/XTextTable.hpp>
Reference< XTextTable > xTable(textTable, UNO_QUERY);
</code>

Note that both method require to include (and then construct) the corresponding hpp file (here XtextTable.hpp) but not for the service because you get it with a method (named « createInstance » in this case). We give a schematic to summarize what we talked about.

[[Image:ComplexUNOQUERY.png]]

'''Last question :''' is it possible to start from any XMultiServiceFactory interface ? The answer to this question is no. Have a look to the code below where I take rOfficeServiceManager instead of oDocMSF because it's a XmultiServiceFactory Interface too.

<code>[cpp]
//Listing 22 Wrong code
// C++
// Reference<XMultiServiceFactory> oDocMSF (xTextDocument,UNO_QUERY);
// using rOfficeServiceManager instead oDocMSF
Reference< XInterface > textTable = rOfficeServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.text.TextTable") );
Reference< XTextTable > xTable(textTable, UNO_QUERY);
if (!xTable.is()) {
printf("Erreur creation XTextTable interface !\n");
return 1;
}
</code>

This code compiles but gives a runtime error. This only means you cannot use every XMultiServiceFactory interface to get every Interface. If you are working with a document ask the corresponding XMultiServiceFactory interface. At this point only experience can help you.

Note before going further that a code used many times so far, can find an explanation even if here the XMultiServiceFactory interface is not obtained in a standard way :

<code>[cpp]
//Listing 23 Classic code
// C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
</code>

Easy to retreive the three instructions style to get the XcomponentLoader, isn't it ?

An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

== Mapping for Modules and Interfaces ==
For instance:
<pre>
// IDL
module M
{ struct E { long L;
};
};
</pre>
is mapped into:
<code>[cpp]
// C++
namespace M
{ struct E
{ Long L; };
}
</code>
and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E:
<code>[cpp]
// C++
using namespace M;
E e;
e.L = 3;
</code>

= Core reflection service and its Interfaces =

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

== XIdlReflection interface ==

This interface is described [[XIDLReflection_Interface |here]]

== The XIntrospection Interface ==

This interface is described [[XIntrospection_Interface |here]] with code's example. Other code is given in [[Constructing_Helpers#Reflection_Helper|Constructing Helpers]] section.
See also [[Extensions_development_basic#Introducing_the_OpenOffice.org_API|Introducing the OpenOffice.org_API]] and [[Extensions_development_basic#Introspection|OOoBasic Introspection]].

= Using Java Inspector =
For an introduction of using Java with OOo, see [[JavaEclipseTuto|Java and Eclipse tutorial]]. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance :
<code>[oobas]
'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC *****
Sub JavaInspector
o = createUnoService("org.OpenOffice.InstanceInspector")
'XRay.XRay o
oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" )
o.inspect(oReflection)
End Sub
</code>
If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed.
We see below in Figure what is the result of this program.

[[Image:Inspector3.png]]

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

# construct a urd file starting from IDL (in makefile)
# don't forget the registry of urd file in makefile
# add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
# copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
# add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
# add this code
<code>[cpp]
// C++
Any toInspect;
toInspect <<= rDesktop;
Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(
OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
xinspect->inspect(toInspect);
</code>
And it works like in OOoBasic. The corresponding Linux makefile is :
<pre>
#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
com.sun.star.uno.XNamingService \
....
com.sun.star.container.XHierarchicalNameAccess \
org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
-mkdir -p $(OUT_COMP_URD)
idlc -I. -I../../../../idl -O$(OUT_COMP_URD) ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
-mkdir -p $(OUT_COMP_BIN)
cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
@echo --------------------------------------------------------------------------------
@echo Register necessary runtime components in $(COMPONENT_RDB)
@echo --------------------------------------------------------------------------------
regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
# @echo bla > $@

$(GENHPPFILES) : $(subst /,$(PS),$(@D))
mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
-mkdir -p $(subst /,$(PS),$(@D))
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
-mkdir -p $(OUT_COMP_OBJ)/
gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx

$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
-mkdir -p $(OUT_COMP_BIN)
gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
$(OUT_COMP_OBJ)/$(HELPER).o \
-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc

ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
@echo --------------------------------------------------------------------------------
@echo Please use one of the following commands to execute the examples!
@echo
@echo make office_connect.run
@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
cd $(OUT_COMP_BIN) && $(OUTBIN)
</pre>

{{Template:Home_Page}}

= See Also =

*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI10.html IDL Files and C++] (Chapter 10 from UNO/C++ document)
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* See also [[Object Inspector|The New Object Inspector]]
* [[Extensions_introspection|Extensions Introspection]]

[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]