mirror of
https://github.com/samba-team/samba.git
synced 2025-01-11 05:18:09 +03:00
r10380: Use pod-style documentation rather then XML-doc, in good perl style.
(This used to be commit fcc1ba97a3)
This commit is contained in:
Jelmer Vernooij
Gerald (Jerry) Carter
parent
3e4f47aaff
commit
cc6fae19ae
@ -3,23 +3,13 @@ WriteMakefile(
|
||||
'NAME' => 'Parse::Pidl',
|
||||
'VERSION_FROM' => 'lib/Parse/Pidl.pm',
|
||||
'EXE_FILES' => [ 'pidl' ],
|
||||
'PMLIBDIRS' => [ 'lib' ],
|
||||
'test' => { 'TESTS' => 'tests/*.pl' }
|
||||
);
|
||||
|
||||
sub MY::postamble {
|
||||
<<'EOT';
|
||||
lib/Parse/Pidl/IDL.pm :: idl.yp
|
||||
yapp -s -m 'Parse::Pidl::IDL' -o 'lib/Parse/Pidl/IDL.pm' idl.yp
|
||||
lib/Parse/Pidl/IDL.pm: idl.yp
|
||||
yapp -s -m 'Parse::Pidl::IDL' -o lib/Parse/Pidl/IDL.pm idl.yp
|
||||
|
||||
doc: pidl.1 pidl.1.html
|
||||
|
||||
XSLTPROC=xsltproc
|
||||
|
||||
%.1: %.1.xml
|
||||
test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
|
||||
|
||||
%.html: %.xml
|
||||
test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $<
|
||||
EOT
|
||||
}
|
||||
|
||||
@ -22,11 +22,6 @@ Run Makefile.PL to generate the Makefile.
|
||||
|
||||
Then run "make install" (as root) to install.
|
||||
|
||||
Documentation:
|
||||
==============
|
||||
Run 'make doc' to generate the manpage and a HTML version of the manpage.
|
||||
This requires the xsltproc utility to be installed.
|
||||
|
||||
Internals overview:
|
||||
===================
|
||||
|
||||
|
||||
@ -7,6 +7,407 @@
|
||||
# Copyright jelmer@samba.org 2005
|
||||
# released under the GNU GPL
|
||||
|
||||
=head1 NAME
|
||||
|
||||
pidl - IDL Compiler written in Perl
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
pidl --help
|
||||
pidl [--outputdir[=OUTNAME]] [--parse-idl-tree] [--dump-idl-tree] [--dump-ndr-tree] [--ndr-header[=OUTPUT]] [--header[=OUTPUT]] [--ejs[=OUTPUT]] [--swig[=OUTPUT]] [--uint-enums] [--ndr-parser[=OUTPUT]] [--client] [--server] [--dcom-proxy] [--com-header] [--warn-compat] [--quiet] [--verbose] [--template] [--eth-parser[=OUTPUT]] [--diff] [--dump-idl] [<idlfile>.idl]...
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
pidl is an IDL compiler written in Perl that aims to be somewhat
|
||||
compatible with the midl compiler. IDL stands for
|
||||
"Interface Definition Language".
|
||||
|
||||
pidl can generate stubs for DCE/RPC server code, DCE/RPC
|
||||
client code and ethereal dissectors for DCE/RPC traffic.
|
||||
|
||||
IDL compilers like pidl take a description
|
||||
of an interface as their input and use it to generate C
|
||||
(though support for other languages may be added later) code that
|
||||
can use these interfaces, pretty print data sent
|
||||
using these interfaces, or even generate ethereal
|
||||
dissectors that can parse data sent over the
|
||||
wire by these interfaces.
|
||||
|
||||
pidl takes IDL files in the same format as is used by midl,
|
||||
converts it to a .pidl file (which contains pidl's internal representation of the interface) and can then generate whatever output you need.
|
||||
.pidl files should be used for debugging purposes only. Write your
|
||||
interface definitions in .idl format.
|
||||
|
||||
The goal of pidl is to implement a IDL compiler that can be used
|
||||
while developing the RPC subsystem in Samba (for
|
||||
both marshalling/unmarshalling and debugging purposes).
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item I<--help>
|
||||
|
||||
Show list of available options.</para></listitem>
|
||||
|
||||
=item I<--outputdir OUTNAME>
|
||||
|
||||
Write output files to the specified directory. Defaults to the current
|
||||
directory.
|
||||
|
||||
=item I<--parse-idl-tree>
|
||||
|
||||
Read internal tree structure from input files rather
|
||||
then assuming they contain IDL.
|
||||
|
||||
=item I<--dump-idl>
|
||||
|
||||
Generate a new IDL file. File will be named OUTNAME.idl.</para></listitem>
|
||||
|
||||
=item I<--header>
|
||||
|
||||
Generate a C header file for the specified interface. Filename defaults to OUTNAME.h.
|
||||
|
||||
=item I<--ndr-header>
|
||||
|
||||
Generate a C header file with the prototypes for the NDR parsers. Filename defaults to ndr_OUTNAME.h.
|
||||
|
||||
=item I<--ndr-parser>
|
||||
|
||||
Generate a C file containing NDR parsers. Filename defaults to ndr_OUTNAME.c.
|
||||
|
||||
=item I<--server>
|
||||
|
||||
Generate boilerplate for the RPC server that implements
|
||||
the interface. Filename defaults to ndr_OUTNAME_s.c.
|
||||
|
||||
=item I<--template>
|
||||
|
||||
Generate stubs for a RPC server that implements the interface. Output will
|
||||
be written to stdout.
|
||||
|
||||
=item I<--eth-parser>
|
||||
|
||||
Generate an Ethereal dissector (in C) for the interface. Filename
|
||||
defaults to packet-dcerpc-OUTNAME.c.
|
||||
|
||||
Pidl will read additional data from an ethereal conformance file if present.
|
||||
Such a file should have the same location as the IDL file but with the
|
||||
extension I<cnf> rather then I<idl>. See below for details on the format of
|
||||
this file.
|
||||
|
||||
=item I<--diff>
|
||||
|
||||
Parse an IDL file, generate a new IDL file based on the internal data
|
||||
structures and see if there are any differences with the original IDL file.
|
||||
Useful for debugging pidl.
|
||||
|
||||
=item I<--dump-idl-tree>
|
||||
|
||||
Tell pidl to dump the internal tree representation of an IDL
|
||||
file the to disk. Useful for debugging pidl.
|
||||
|
||||
=item I<--dump-ndr-tree>
|
||||
|
||||
Tell pidl to dump the internal NDR information tree it generated
|
||||
from the IDL file to disk. Useful for debugging pidl.
|
||||
|
||||
=back
|
||||
|
||||
=head1 IDL SYNTAX
|
||||
|
||||
IDL files are always preprocessed using the C preprocessor.
|
||||
|
||||
Pretty much everything in an interface (the interface itself, functions,
|
||||
parameters) can have attributes (or properties whatever name you give them).
|
||||
Attributes always prepend the element they apply to and are surrounded
|
||||
by square brackets ([]). Multiple attributes are separated by comma's;
|
||||
arguments to attributes are specified between parentheses.
|
||||
|
||||
See the section COMPATIBILITY for the list of attributes that
|
||||
pidl supports.
|
||||
|
||||
C-style comments can be used.
|
||||
|
||||
=head2 CONFORMANT ARRAYS
|
||||
|
||||
A conformant array is one with that ends in [*] or []. The strange
|
||||
things about conformant arrays are:
|
||||
|
||||
=over 1
|
||||
=item they can only appear as the last element of a structure
|
||||
=item the array size appears before the structure itself on the wire.
|
||||
=back
|
||||
|
||||
So, in this example:
|
||||
|
||||
typedef struct {
|
||||
long abc;
|
||||
long count;
|
||||
long foo;
|
||||
[size_is(count)] long s[*];
|
||||
} Struct1;
|
||||
|
||||
it appears like this:
|
||||
|
||||
[size_is] [abc] [count] [foo] [s...]
|
||||
|
||||
the first [size_is] field is the allocation size of the array, and
|
||||
occurs before the array elements and even before the structure
|
||||
alignment.
|
||||
|
||||
Note that size_is() can refer to a constant, but that doesn't change
|
||||
the wire representation. It does not make the array a fixed array.
|
||||
|
||||
midl.exe would write the above array as the following C header:
|
||||
|
||||
typedef struct {
|
||||
long abc;
|
||||
long count;
|
||||
long foo;
|
||||
long s[1];
|
||||
} Struct1;
|
||||
|
||||
pidl takes a different approach, and writes it like this:
|
||||
|
||||
typedef struct {
|
||||
long abc;
|
||||
long count;
|
||||
long foo;
|
||||
long *s;
|
||||
} Struct1;
|
||||
|
||||
=head2 VARYING ARRAYS
|
||||
|
||||
A varying array looks like this:
|
||||
|
||||
typedef struct {
|
||||
long abc;
|
||||
long count;
|
||||
long foo;
|
||||
[size_is(count)] long *s;
|
||||
} Struct1;
|
||||
|
||||
This will look like this on the wire:
|
||||
|
||||
[abc] [count] [foo] [PTR_s] [count] [s...]
|
||||
|
||||
=head2 FIXED ARRAYS
|
||||
|
||||
A fixed array looks like this:
|
||||
|
||||
typedef struct {
|
||||
long s[10];
|
||||
} Struct1;
|
||||
|
||||
The NDR representation looks just like 10 separate long
|
||||
declarations. The array size is not encoded on the wire.
|
||||
|
||||
pidl also supports "inline" arrays, which are not part of the IDL/NDR
|
||||
standard. These are declared like this:
|
||||
|
||||
typedef struct {
|
||||
uint32 foo;
|
||||
uint32 count;
|
||||
uint32 bar;
|
||||
long s[count];
|
||||
} Struct1;
|
||||
|
||||
This appears like this:
|
||||
|
||||
[foo] [count] [bar] [s...]
|
||||
|
||||
Fixed arrays are an extension added to support some of the strange
|
||||
embedded structures in security descriptors and spoolss.
|
||||
|
||||
This section is by no means complete. See the OpenGroup and MSDN
|
||||
documentation for additional information.
|
||||
|
||||
=head1 COMPATIBILITY WITH MIDL
|
||||
|
||||
=head2 Missing features in pidl
|
||||
|
||||
The following MIDL features are not (yet) implemented in pidl
|
||||
or are implemented with an incompatible interface:
|
||||
|
||||
=over
|
||||
=item Asynchronous communication
|
||||
=item Typelibs (.tlb files)
|
||||
=item Datagram support (ncadg_*)
|
||||
=back
|
||||
|
||||
=head2 Supported attributes
|
||||
|
||||
in, out, ref, length_is, switch_is, size_is, uuid, case, default, string,
|
||||
unique, ptr, pointer_default, v1_enum, object, helpstring, range, local,
|
||||
call_as, endpoint, switch_type, progid, coclass, iid_is.
|
||||
|
||||
=head2 PIDL Specific properties
|
||||
|
||||
=over 4
|
||||
|
||||
=item public
|
||||
|
||||
The [public] property on a structure or union is a pidl extension that
|
||||
forces the generated pull/push functions to be non-static. This allows
|
||||
you to declare types that can be used between modules. If you don't
|
||||
specify [public] then pull/push functions for other than top-level
|
||||
functions are declared static.
|
||||
|
||||
=item noprint
|
||||
|
||||
The [noprint] property is a pidl extension that allows you to specify
|
||||
that pidl should not generate a ndr_print_*() function for that
|
||||
structure or union. This is used when you wish to define your own
|
||||
print function that prints a structure in a nicer manner. A good
|
||||
example is the use of [noprint] on dom_sid, which allows the
|
||||
pretty-printing of SIDs.
|
||||
|
||||
=item value
|
||||
|
||||
The [value(expression)] property is a pidl extension that allows you
|
||||
to specify the value of a field when it is put on the wire. This
|
||||
allows fields that always have a well-known value to be automatically
|
||||
filled in, thus making the API more programmer friendly. The
|
||||
expression can be any C expression.
|
||||
|
||||
=item relative
|
||||
|
||||
The [relative] property can be supplied on a pointer. When it is used
|
||||
it declares the pointer as a spoolss style "relative" pointer, which
|
||||
means it appears on the wire as an offset within the current
|
||||
encapsulating structure. This is not part of normal IDL/NDR, but it is
|
||||
a very useful extension as it avoids the manual encoding of many
|
||||
complex structures.
|
||||
|
||||
=item subcontext(length)
|
||||
|
||||
Specifies that a size of I<length>
|
||||
bytes should be read, followed by a blob of that size,
|
||||
which will be parsed as NDR.
|
||||
|
||||
=item flag
|
||||
|
||||
Specify boolean options, mostly used for
|
||||
low-level NDR options. Several options
|
||||
can be specified using the | character.
|
||||
Note that flags are inherited by substructures!
|
||||
|
||||
=item nodiscriminant
|
||||
|
||||
The [nodiscriminant] property on a union means that the usual uint16
|
||||
discriminent field at the start of the union on the wire is
|
||||
omitted. This is not normally allowed in IDL/NDR, but is used for some
|
||||
spoolss structures.
|
||||
|
||||
=item charset(name)
|
||||
|
||||
Specify that the array or string uses the specified
|
||||
charset. If this attribute is specified, pidl will
|
||||
take care of converting the character data from this format
|
||||
to the host format. Commonly used values are UCS2, DOS and UTF8.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Unsupported MIDL properties
|
||||
|
||||
aggregatable, appobject, async_uuid, bindable, control, cpp_quote,
|
||||
defaultbind, defaultcollelem, defaultvalue, defaultvtable, dispinterface,
|
||||
displaybind, dual, entry, first_is, helpcontext, helpfile, helpstringcontext,
|
||||
helpstringdll, hidden, idl_module, idl_quote, id, immediatebind, importlib,
|
||||
import, include, includelib, last_is, lcid, licensed, max_is, module,
|
||||
ms_union, no_injected_text, nonbrowsable, noncreatable, nonextensible, odl,
|
||||
oleautomation, optional, pragma, propget, propputref, propput, readonly,
|
||||
requestedit, restricted, retval, source, transmit_as, uidefault,
|
||||
usesgetlasterror, vararg, vi_progid, wire_marshal.
|
||||
|
||||
=head1 ETHEREAL CONFORMANCE FILES
|
||||
|
||||
Pidl needs additional data for ethereal output. This data is read from
|
||||
so-called conformance files. This section describes the format of these
|
||||
files.
|
||||
|
||||
Conformance files are simple text files with a single command on each line.
|
||||
Empty lines and lines starting with a '#' character are ignored.
|
||||
Arguments to commands are seperated by spaces.
|
||||
|
||||
The following commands are currently supported:
|
||||
|
||||
=over 4
|
||||
|
||||
=item TYPE name dissector ft_type base_type mask valsstring alignment
|
||||
|
||||
Register new data type with specified name, what dissector function to call
|
||||
and what properties to give header fields for elements of this type.
|
||||
|
||||
=item NOEMIT type
|
||||
|
||||
Suppress emitting a dissect_type function for the specified type
|
||||
|
||||
=item PARAM_VALUE type param
|
||||
|
||||
Set parameter to specify to dissector function for given type.
|
||||
|
||||
=item HF_FIELD hf title filter ft_type base_type valsstring mask description
|
||||
|
||||
Generate a custom header field with specified properties.
|
||||
|
||||
=item HF_RENAME old_hf_name new_hf_name
|
||||
|
||||
Force the use of new_hf_name when the parser generator was going to
|
||||
use old_hf_name.
|
||||
|
||||
This can be used in conjunction with HF_FIELD in order to make more then
|
||||
one element use the same filter name.
|
||||
|
||||
=item STRIP_PREFIX prefix
|
||||
|
||||
Remove the specified prefix from all function names (if present).
|
||||
|
||||
=item PROTOCOL longname shortname filtername
|
||||
|
||||
Change the short-, long- and filter-name for the current interface in
|
||||
Ethereal.
|
||||
|
||||
=item FIELD_DESCRIPTION field desc
|
||||
|
||||
Change description for the specified header field. `field' is the hf name of the field.
|
||||
|
||||
=item IMPORT dissector code...
|
||||
|
||||
Code to insert when generating the specified dissector. @HF@ and
|
||||
@PARAM@ will be substituted.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
# Generating an ethereal parser
|
||||
$ ./pidl --eth-parser -- atsvc.idl
|
||||
|
||||
# Generating a TDR parser
|
||||
$ ./pidl --tdr-parser --tdr-header --header -- regf.idl
|
||||
|
||||
=head1 VERSION
|
||||
|
||||
This man page is correct for version 4.0 of the Samba suite. L<http://www.samba.org/>.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<http://msdn.microsoft.com/library/en-us/rpc/rpc/field_attributes.asp>
|
||||
L<http://wiki.ethereal.com/DCE/RPC>
|
||||
yapp(1)
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim Potter and Jelmer
|
||||
Vernooij.
|
||||
|
||||
This manpage was written by Jelmer Vernooij, partially based on the original
|
||||
pidl README by Andrew Tridgell.
|
||||
|
||||
=cut
|
||||
|
||||
use strict;
|
||||
use FindBin qw($RealBin);
|
||||
use lib "$RealBin";
|
||||
|
||||
@ -1,606 +0,0 @@
|
||||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
|
||||
<refentry id="pidl.1">
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>pidl</refentrytitle>
|
||||
<manvolnum>1</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>pidl</refname>
|
||||
<refpurpose>IDL Compiler written in Perl</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<cmdsynopsis>
|
||||
<command>pidl</command>
|
||||
<arg choice="opt">--help</arg>
|
||||
<arg choice="opt">--outputdir OUTNAME</arg>
|
||||
<arg choice="opt">--parse-idl-tree</arg>
|
||||
<arg choice="opt">--dump-idl-tree</arg>
|
||||
<arg choice="opt">--dump-ndr-tree</arg>
|
||||
<arg choice="opt">--ndr-header[=OUTPUT]</arg>
|
||||
<arg choice="opt">--header[=OUTPUT]</arg>
|
||||
<arg choice="opt">--ejs[=OUTPUT]</arg>
|
||||
<arg choice="opt">--swig[=OUTPUT]</arg>
|
||||
<arg choice="opt">--uint-enums</arg>
|
||||
<arg choice="opt">--ndr-parser[=OUTPUT]</arg>
|
||||
<arg choice="opt">--client</arg>
|
||||
<arg choice="opt">--server</arg>
|
||||
<arg choice="opt">--dcom-proxy</arg>
|
||||
<arg choice="opt">--com-header</arg>
|
||||
<arg choice="opt">--warn-compat</arg>
|
||||
<arg choice="opt">--quiet</arg>
|
||||
<arg choice="opt">--verbose</arg>
|
||||
<arg choice="opt">--template</arg>
|
||||
<arg choice="opt">--eth-parser[=OUTPUT]</arg>
|
||||
<arg choice="opt">--diff</arg>
|
||||
<arg choice="opt">--dump-idl</arg>
|
||||
<arg choice="req">idlfile</arg>
|
||||
<arg choice="opt">idlfile2</arg>
|
||||
<arg choice="opt">...</arg>
|
||||
</cmdsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
|
||||
<para>pidl is an IDL compiler written in Perl that aims to be somewhat
|
||||
compatible with the midl compiler. IDL stands for
|
||||
"Interface Definition Language".</para>
|
||||
|
||||
<para>pidl can generate stubs for DCE/RPC server code, DCE/RPC
|
||||
client code and ethereal dissectors for DCE/RPC traffic.</para>
|
||||
|
||||
<para>IDL compilers like <emphasis>pidl</emphasis> take a description
|
||||
of an interface as their input and use it to generate C
|
||||
(though support for other languages may be added later) code that
|
||||
can use these interfaces, pretty print data sent
|
||||
using these interfaces, or even generate ethereal
|
||||
dissectors that can parse data sent over the
|
||||
wire by these interfaces. </para>
|
||||
|
||||
<para>pidl takes IDL files in the same format as is used by midl,
|
||||
converts it to a .pidl file (which contains pidl's internal representation of the interface) and can then generate whatever output you need.
|
||||
.pidl files should be used for debugging purposes only. Write your
|
||||
interface definitions in .idl format.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The goal of pidl is to implement a IDL compiler that can be used
|
||||
while developing the RPC subsystem in Samba (for
|
||||
both marshalling/unmarshalling and debugging purposes).
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>OPTIONS</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>--help</term>
|
||||
<listitem><para>
|
||||
Show list of available options.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>--outputdir OUTNAME</term>
|
||||
<listitem><para>Write output files to the specified directory.
|
||||
Defaults to the current directory.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>--parse-idl-tree</term>
|
||||
<listitem><para>
|
||||
Read internal tree structure from input files rather
|
||||
then assuming they contain IDL.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>--dump-idl</term>
|
||||
<listitem><para>
|
||||
Generate a new IDL file. File will be named OUTNAME.idl.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>--header</term>
|
||||
<listitem><para>
|
||||
Generate a C header file for the specified interface. Filename defaults to OUTNAME.h.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>--ndr-header</term>
|
||||
<listitem><para>
|
||||
Generate a C header file with the prototypes for the NDR parsers. Filename defaults to ndr_OUTNAME.h.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>--ndr-parser</term>
|
||||
<listitem><para>
|
||||
Generate a C file containing NDR parsers.
|
||||
Filename defaults to ndr_OUTNAME.c.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>--server</term>
|
||||
<listitem><para>
|
||||
Generate boilerplate for the RPC server that implements
|
||||
the interface. Filename defaults to ndr_OUTNAME_s.c</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>--template</term>
|
||||
<listitem><para>
|
||||
Generate stubs for a RPC server that implements
|
||||
the interface. Output will be written to stdout.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>--eth-parser</term>
|
||||
<listitem><para>
|
||||
Generate an Ethereal dissector (in C) for the interface. Filename
|
||||
defaults to packet-dcerpc-OUTNAME.c.
|
||||
</para>
|
||||
|
||||
<para>Pidl will read additional data
|
||||
from an ethereal conformance file if present. Such a file should
|
||||
have the same location as the IDL file but with the extension
|
||||
<quote>cnf</quote> rather then <quote>idl</quote>. See
|
||||
below for details on the format of this file.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>--diff</term>
|
||||
<listitem><para>
|
||||
Parse an IDL file, generate a new IDL file based
|
||||
on the internal data structures and see if there are
|
||||
any differences with the
|
||||
original IDL file. Useful for debugging pidl.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>--dump-idl-tree</term>
|
||||
<listitem><para>
|
||||
Tell pidl to dump the internal tree representation of an IDL
|
||||
file the to disk. Useful
|
||||
for debugging pidl.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>--dump-ndr-tree</term>
|
||||
<listitem><para>
|
||||
Tell pidl to dump the internal NDR information tree it generated
|
||||
from the IDL file to disk. Useful for debugging pidl.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>IDL SYNTAX</title>
|
||||
|
||||
<para>IDL files are always preprocessed using the C preprocessor.</para>
|
||||
|
||||
<para>Pretty much everything in an interface (the interface itself,
|
||||
functions, parameters) can have attributes (or properties
|
||||
whatever name you give them). Attributes
|
||||
always prepend the element they apply to and are surrounded
|
||||
by square brackets ([]). Multiple attributes
|
||||
are separated by comma's; arguments to attributes are
|
||||
specified between parentheses. </para>
|
||||
|
||||
<para>See the section COMPATIBILITY for the list of attributes that
|
||||
pidl supports.</para>
|
||||
|
||||
<para>C-style comments can be used.</para>
|
||||
|
||||
<refsect2>
|
||||
<title>CONFORMANT ARRAYS</title>
|
||||
|
||||
<para>
|
||||
A conformant array is one with that ends in [*] or []. The strange
|
||||
things about conformant arrays are:
|
||||
</para>
|
||||
|
||||
<simplelist>
|
||||
<member>they can only appear as the last element of a structure</member>
|
||||
<member>the array size appears before the structure itself on the wire. </member>
|
||||
</simplelist>
|
||||
|
||||
<para>
|
||||
So, in this example:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
typedef struct {
|
||||
long abc;
|
||||
long count;
|
||||
long foo;
|
||||
[size_is(count)] long s[*];
|
||||
} Struct1;
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
it appears like this:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
[size_is] [abc] [count] [foo] [s...]
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
the first [size_is] field is the allocation size of the array, and
|
||||
occurs before the array elements and even before the structure
|
||||
alignment.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note that size_is() can refer to a constant, but that doesn't change
|
||||
the wire representation. It does not make the array a fixed array.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
midl.exe would write the above array as the following C header:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
typedef struct {
|
||||
long abc;
|
||||
long count;
|
||||
long foo;
|
||||
long s[1];
|
||||
} Struct1;
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
pidl takes a different approach, and writes it like this:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
typedef struct {
|
||||
long abc;
|
||||
long count;
|
||||
long foo;
|
||||
long *s;
|
||||
} Struct1;
|
||||
</programlisting>
|
||||
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>VARYING ARRAYS</title>
|
||||
|
||||
<para>
|
||||
A varying array looks like this:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
typedef struct {
|
||||
long abc;
|
||||
long count;
|
||||
long foo;
|
||||
[size_is(count)] long *s;
|
||||
} Struct1;
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
This will look like this on the wire:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
[abc] [count] [foo] [PTR_s] [count] [s...]
|
||||
</programlisting>
|
||||
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>FIXED ARRAYS</title>
|
||||
|
||||
<para>
|
||||
A fixed array looks like this:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
typedef struct {
|
||||
long s[10];
|
||||
} Struct1;
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
The NDR representation looks just like 10 separate long
|
||||
declarations. The array size is not encoded on the wire.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
pidl also supports "inline" arrays, which are not part of the IDL/NDR
|
||||
standard. These are declared like this:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
typedef struct {
|
||||
uint32 foo;
|
||||
uint32 count;
|
||||
uint32 bar;
|
||||
long s[count];
|
||||
} Struct1;
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
This appears like this:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
[foo] [count] [bar] [s...]
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
Fixed arrays are an extension added to support some of the strange
|
||||
embedded structures in security descriptors and spoolss.
|
||||
</para>
|
||||
|
||||
</refsect2>
|
||||
|
||||
<para>This section is by no means complete. See the OpenGroup and MSDN
|
||||
documentation for additional information.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>COMPATIBILITY WITH MIDL</title>
|
||||
|
||||
<refsect2>
|
||||
<title>Missing features in pidl</title>
|
||||
<para>
|
||||
The following MIDL features are not (yet) implemented in pidl
|
||||
or are implemented with an incompatible interface:
|
||||
</para>
|
||||
|
||||
<simplelist>
|
||||
<member>Asynchronous communication</member>
|
||||
<member>Typelibs (.tlb files)</member>
|
||||
<member>Datagram support (ncadg_*)</member>
|
||||
</simplelist>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Supported properties (attributes is the MIDL term)</title>
|
||||
|
||||
<para>
|
||||
in, out, ref, length_is, switch_is, size_is, uuid, case, default, string, unique, ptr, pointer_default, v1_enum, object, helpstring, range, local, call_as, endpoint, switch_type, progid, coclass, iid_is.
|
||||
</para>
|
||||
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>PIDL Specific properties</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry><term>public</term>
|
||||
<listitem><para>
|
||||
The [public] property on a structure or union is a pidl extension that
|
||||
forces the generated pull/push functions to be non-static. This allows
|
||||
you to declare types that can be used between modules. If you don't
|
||||
specify [public] then pull/push functions for other than top-level
|
||||
functions are declared static.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>noprint</term>
|
||||
<listitem><para>
|
||||
The [noprint] property is a pidl extension that allows you to specify
|
||||
that pidl should not generate a ndr_print_*() function for that
|
||||
structure or union. This is used when you wish to define your own
|
||||
print function that prints a structure in a nicer manner. A good
|
||||
example is the use of [noprint] on dom_sid, which allows the
|
||||
pretty-printing of SIDs.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>value</term>
|
||||
<listitem><para>
|
||||
The [value(expression)] property is a pidl extension that allows you
|
||||
to specify the value of a field when it is put on the wire. This
|
||||
allows fields that always have a well-known value to be automatically
|
||||
filled in, thus making the API more programmer friendly. The
|
||||
expression can be any C expression.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>relative</term>
|
||||
<listitem><para>
|
||||
The [relative] property can be supplied on a pointer. When it is used
|
||||
it declares the pointer as a spoolss style "relative" pointer, which
|
||||
means it appears on the wire as an offset within the current
|
||||
encapsulating structure. This is not part of normal IDL/NDR, but it is
|
||||
a very useful extension as it avoids the manual encoding of many
|
||||
complex structures.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>subcontext(length)</term>
|
||||
<listitem><para>
|
||||
Specifies that a size of <replaceable>length</replaceable>
|
||||
bytes should be read, followed by a blob of that size,
|
||||
which will be parsed as NDR.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>flag</term>
|
||||
<listitem><para>
|
||||
Specify boolean options, mostly used for
|
||||
low-level NDR options. Several options
|
||||
can be specified using the | character.
|
||||
Note that flags are inherited by substructures!
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>nodiscriminant</term>
|
||||
<listitem><para>
|
||||
The [nodiscriminant] property on a union means that the usual uint16
|
||||
discriminent field at the start of the union on the wire is
|
||||
omitted. This is not normally allowed in IDL/NDR, but is used for some
|
||||
spoolss structures.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>charset(name)</term>
|
||||
<listitem><para>
|
||||
Specify that the array or string uses the specified
|
||||
charset. If this attribute is specified, pidl will
|
||||
take care of converting the character data from this format
|
||||
to the host format. Commonly used values are UCS2, DOS and UTF8.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Unsupported MIDL properties</title>
|
||||
|
||||
<para>aggregatable, appobject, async_uuid, bindable, control, cpp_quote, defaultbind, defaultcollelem, defaultvalue, defaultvtable, dispinterface, displaybind, dual, entry, first_is, helpcontext, helpfile, helpstringcontext, helpstringdll, hidden, idl_module, idl_quote, id, immediatebind, importlib, import, include, includelib, last_is, lcid, licensed, max_is, module, ms_union, no_injected_text, nonbrowsable, noncreatable, nonextensible, odl, oleautomation, optional, pragma, propget, propputref, propput, readonly, requestedit, restricted, retval, source, transmit_as, uidefault, usesgetlasterror, vararg, vi_progid, wire_marshal. </para>
|
||||
|
||||
</refsect2>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>ETHEREAL CONFORMANCE FILES</title>
|
||||
|
||||
<para>
|
||||
Pidl needs additional data for ethereal output. This data is read from
|
||||
so-called conformance files. This section describes the format of these
|
||||
files.</para>
|
||||
|
||||
<para>
|
||||
Conformance files are simple text files with a single command on each line.
|
||||
Empty lines and lines starting with a '#' character are ignored.
|
||||
Arguments to commands are seperated by spaces.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following commands are currently supported:
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>TYPE name dissector ft_type base_type mask valsstring alignment</term>
|
||||
<listitem><para>Register new data type with specified name, what dissector function to call and what properties to give header fields for elements of this type.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>NOEMIT type</term>
|
||||
<listitem><para>
|
||||
Suppress emitting a dissect_type function for the specified type
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>PARAM_VALUE type param</term>
|
||||
<listitem><para>
|
||||
Set parameter to specify to dissector function for given type.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>HF_FIELD hf title filter ft_type base_type valsstring mask description</term>
|
||||
<listitem><para>
|
||||
Generate a custom header field with specified properties.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>HF_RENAME old_hf_name new_hf_name</term>
|
||||
<listitem><para>
|
||||
Force the use of new_hf_name when the parser generator was going to
|
||||
use old_hf_name.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This can be used in conjunction with HF_FIELD in order to make more then
|
||||
one element use the same filter name.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>STRIP_PREFIX prefix</term>
|
||||
<listitem><para>
|
||||
Remove the specified prefix from all function names (if present).
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>PROTOCOL longname shortname filtername</term>
|
||||
<listitem><para>
|
||||
Change the short-, long- and filter-name for the current interface in
|
||||
Ethereal.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>FIELD_DESCRIPTION field desc</term>
|
||||
<listitem><para>Change description for the specified header field. `field' is the hf name of the field.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>IMPORT dissector code...</term>
|
||||
<listitem><para>
|
||||
Code to insert when generating the specified dissector. @HF@ and
|
||||
@PARAM@ will be substituted.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>EXAMPLES</title>
|
||||
|
||||
<programlisting>
|
||||
# Generating an ethereal parser
|
||||
$ ./pidl --eth-parser -- atsvc.idl
|
||||
|
||||
# Generating a TDR parser
|
||||
$ ./pidl --tdr-parser --tdr-header --header -- regf.idl
|
||||
</programlisting>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>VERSION</title>
|
||||
|
||||
<para>This man page is correct for version 4.0 of the Samba suite.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
|
||||
<para><ulink url="http://msdn.microsoft.com/library/en-us/rpc/rpc/field_attributes.asp">Field Attributes [Remote Procedure Call]</ulink>, <ulink url="http://wiki.ethereal.com/DCE/RPC">Ethereal Wiki on DCE/RPC</ulink>.</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>AUTHOR</title>
|
||||
|
||||
<para>pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim
|
||||
Potter and Jelmer Vernooij. </para>
|
||||
|
||||
<para>This manpage was written by Jelmer Vernooij, partially based on the original pidl README by Andrew Tridgell. </para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
Loading…
Reference in New Issue
Block a user