r137: Add notes about handles in dcesrv pipes

[jelmer/samba4-debian.git] / prog_guide.txt

diff --git a/prog_guide.txt b/prog_guide.txt
index 8eac3ebe537bced79ebce5a3725e1b10a931cefa..e972d4482e70e6a6b45b572d9dc6f0538deb5286 100644 (file)
--- a/prog_guide.txt
+++ b/prog_guide.txt
@@ -2,8 +2,6 @@ THIS IS INCOMPLETE! I'M ONLY COMMITING IT IN ORDER TO SOLICIT COMMENTS
 FROM A FEW PEOPLE. DON'T TAKE THIS AS THE FINAL VERSION YET.
 
 
-
-
 Samba4 Programming Guide
 ------------------------
 
@@ -554,10 +552,30 @@ DCERPC binding strings
 ----------------------
 
 When connecting to a dcerpc service you need to specify a binding
-string. Because I'm too lazy to write proper docs, here are some
-examples that should give you the idea:
+string. 
+
+The format is:
+
+  TRANSPORT:host:[flags]
+
+where TRANSPORT is either ncacn_np for SMB or ncacn_ip_tcp for RPC/TCP
+
+"host" is an IP or hostname or netbios name
 
-These all connect to the samr pipe:
+"flags" can include a SMB pipe name if using the ncacn_np transport or
+a TCP port number if using the ncacn_ip_tcp transport, otherwise they
+will be auto-determined.
+
+other recognised flags are:
+
+  sign : enable ntlmssp signing
+  seal : enable ntlmssp sealing
+  validate: enable the NDR validator
+  print: enable debugging of the packets
+  bigendian: use bigendian RPC
+
+
+For example, these all connect to the samr pipe:
 
    ncacn_np:myserver
    ncacn_np:myserver:samr
@@ -567,9 +585,9 @@ These all connect to the samr pipe:
    ncacn_np:myserver[samr]
    ncacn_np:myserver[\pipe\samr]
    ncacn_np:myserver[/pipe/samr]
-   ncacn_np:myserver:[samr,sign]
-   ncacn_np:myserver:[\pipe\samr,sign,seal]
-   ncacn_np:myserver:[/pipe/samr,seal]
+   ncacn_np:myserver:[samr,sign,print]
+   ncacn_np:myserver:[\pipe\samr,sign,seal,bigendian]
+   ncacn_np:myserver:[/pipe/samr,seal,validate]
 
    ncacn_ip_tcp:myserver
    ncacn_ip_tcp:myserver:1024
@@ -577,6 +595,25 @@ These all connect to the samr pipe:
    ncacn_ip_tcp:myserver:[1024,sign,seal]
 
 
+IDEA: Maybe extend UNC names like this?
+
+ smbclient //server/share
+ smbclient //server/share:[sign,seal,spnego]
+
+DCERPC Handles
+--------------
+The various handles that are used in the RPC servers should be created and 
+fetch using the dcesrv_handle_* functions.
+
+Use dcesrv_handle_new(struct dcesrv_connection *, uint8 handle_type) to obtain 
+a new handle of the specified type. Handle types are unique within each 
+pipe.
+
+The handle can later be fetched again using
+struct dcesrv_handle *dcesrv_handle_fetch(struct dcesrv_connection *dce_conn, struct policy_handle *p, uint8 handle_type)
+and destroyed by dcesrv_handle_destroy(struct dcesrv_handle *).
+
+User data should be stored in the 'data' member of the dcesrv_handle struct.
 
 
 MSRPC
@@ -716,3 +753,10 @@ docs
 
   conference paper
   developer docs
+
+svn instructions
+
+test commit
+
+
+