Artifact 70e97d53eb6ab0bcdf859c1691df79d5a5b18db3:
- File
docs/Creating a Tcl Web Service.html
— part of check-in
[1a39cd9cf0]
at
2010-11-12 18:08:07
on branch proposed-main
— change eol-style to native
git-svn-id: http://tclws.googlecode.com/svn/trunk@65 4eab59b1-ed42-0410-973d-ab9b78d4c8bc (user: jeff@bovine.net@4eab59b1-ed42-0410-973d-ab9b78d4c8bc size: 7995)
<HTML lang=en dir=ltr xml:lang="en" xmlns="http://www.w3.org/1999/xhtml"> <HEAD> <TITLE>Creating a Tcl Web Service</TITLE> <META http-equiv=Content-Type content="text/html; charset=utf-8"> <META content="Creating a Tcl Web Service" name=KEYWORDS> </HEAD> <BODY> <H1>Creating a Tcl Web Service</H1> <TABLE class=toc id=toc> <TR> <TD> <DIV id=toctitle> <H2>Contents</H2></DIV> <UL> <LI class=toclevel-1><A href="#Loading_the_Webservices_Server_Package"><SPAN class=tocnumber>1</SPAN> <SPAN class=toctext>Loading the Webservices Server Package</SPAN></A> <LI class=toclevel-1><A href="#Defining_a_Service"><SPAN class=tocnumber>2</SPAN> <SPAN class=toctext>Defining a Service</SPAN></A> <LI class=toclevel-1><A href="#Defining_an_Operation_.28aka_a_Service_Procedure.29"><SPAN class=tocnumber>3</SPAN> <SPAN class=toctext>Defining an Operation (aka a Service Procedure)</SPAN></A> <LI class=toclevel-1><A href="#Declaring_Complex_Types"><SPAN class=tocnumber>4</SPAN> <SPAN class=toctext>Declaring Complex Types</SPAN></A> </LI></UL></TD></TR></TBODY></TABLE> <A name=Loading_the_Webservices_Server_Package></A> <H2>Loading the Webservices Server Package </H2> <P>To load the webservices server package, do: </P><PRE> package require WS::Server </PRE> <P>This command will only load the server the first time it is used, so it causes no ill effects to put this in each file declaring a service or service procedure. </P> <h3>Using as part of TclHttpd</h3> <P> The Web Services package, WS::Server, is not a standalone application, but rather is designed be a "module" of TclHttpd. The following command is normally placed in httpdthread.tcl: </P> <h3>Embedding in a Standalone Application</h3> <P> To embed a Web Service into an application, the application needs to be event driven and you also need to use the <B>WS::Embeded</b> package. You also must define the service with the <i>-mode=embedded</i> option. </P> <P> See also <A HREF="Embedded Web Service.html">Embeding a Web Service into an application</A>. </P> <HR> <A name=Defining_a_Service></A> <H2>Defining a Service </H2> <P> The code that defines a service is normally placed in one or more files in the custom directory. </P> <P><B>Procedure Name : <I>::WS::Server::Service</I></B> </P> <P><B>Description</B> : Declare a Web Service, the following URLs will exist </P><PRE> /service/<ServiceName> Displays an HTML page describing the service /service/<ServiceName>/wsdl Returns a WSDL describing the service /service/<ServiceName>/op Invoke an operation </PRE> <P><B>Arguments</B> : this procedure uses position independed arguments, they are: </P><PRE> -host - The host name for this serice Defaults to "localhost" -decription - The HTML description for this service -xmlnamespace - Extra XML namespaces used by the service -service - The service name (this will also be used for the Tcl namespace of the procedures that implement the operations. -premonitor - This is a command prefix to be called before an operation is called. The following arguments are added to the command prefix: PRE serviceName operationName operArgList -postmonitor - This is a command prefix to be called after an operation is called. The following arguments are added to the command prefix: POST serviceName operationName OK|ERROR results -inheaders - List of input header types. -outheaders - List of output header types. -checkheader - Command prefix to check headers. If the call is not to be allowed, this command should raise an error. The signature of the command must be: cmd \ service \ operation \ caller_ipaddr \ http_header_list \ soap_header_list -mode - Mode that service is running in. Must be one of: tclhhtpd -- running inside of tclhttpd or an evironment that supplies a compatilbe Url_PrefixInstall and Httpd_ReturnData commands embedded -- using the ::WS::Embedded package -ports - List of ports for embedded mode. Default: 80 NOTE -- a call should be to ::WS::Embedded::Listen for each port in this list prior to this call </PRE> <P><B>Returns</B> : Nothing </P> <P><B>Side-Effects</B> : None </P> <P><B>Exception Conditions</B> : </P><PRE> <I>MISSREQARG</I> -- Missing required arguements </PRE> <P><B>Pre-requisite Conditions</B> : None </P> <HR> <A name=Defining_an_Operation_.28aka_a_Service_Procedure.29></A> <H2>Defining an Operation (aka a Service Procedure) </H2> <P><B>Procedure Name : <I>::WS::Server::ServiceProc</I></B> </P> <P><B>Description</B> : Register an operation for a service and declare the procedure to handle the operations. </P> <P><B>Arguments</B> : </P><PRE> <I>ServiceName </I> -- Name of the service this operation is for <I>NameInfo </I> -- List of three elements: 1) OperationName -- the name of the operation 2) ReturnType -- the type of the procedure return, this can be a simple or complex type 3) Description -- description of the return method <I>Arglist </I> -- List of argument definitions, each list element must be of the form: 1) ArgumentName -- the name of the argument 2) ArgumentTypeInfo -- -- A list of: {type typeName comment commentString} typeName can be any simple or defined type. commentString is a quoted string describing the field <I>Documentation</I> -- HTML describing what this operation does <I>Body </I> -- The tcl code to be called when the operation is invoked. This code should return a dictionary with <OperationName>Result as a key and the operation's result as the value. </PRE> <P><B>Returns</B> : Nothing </P> <P><I>Side-Effects</I> : </P><PRE> A proceedure named "<ServiceName>::<OperationName>" defined A type name with the name <OperationName>Result is defined. </PRE> <P><I>Exception Conditions</I> : None </P> <P><I>Pre-requisite Conditions</I> : ::WS::Server::Server must have been called for the ServiceName </P> <HR> <A name=Declaring_Complex_Types></A> <H2>Declaring Complex Types </H2> <P>See: <A title="Creating a Web Service Type from Tcl" href="Creating a Web Service Type.html">Creating a Web Service Type from Tcl</A> </P> </BODY> </HTML>