eduardok/libsmbclient-php — pull request #4 by aklomp (2014-03-14 20:12:47+00:00)
Title: Add state resource: must now register state first for effiency gains

Hi, here's a new pull request. (I know I'm added as contributor, but I like the extra eyes on the code :)

This set of changes is perhaps the most intrusive so far, because it breaks backwards API compatibility pretty hard. All function signatures have changed. The end user must now obtain a state resource before he can use any of the file functions, and pass that state resource to every function that's called. I think the change is worth it (as explained below), but it's something to consider.

Okay, so this changeset introduces the concept of the "state resource". This mirrors the underlying library's use of the `SMBCCTX` context to reuse established connections. This resource is like for instance an ldap resource or a mysql resource: you have to create it before you start, pass it to all your functions, and destroy it when you're finished. Here's why I think this is a good (and necessary) change:

* Allows libsmbclient to reuse an already established connection instead of reconnecting for every query. This one is huge in terms of efficiency.
* No more usernames and passwords in URI's - they are set once during the init stage and are owned by the context. Keep the logs clean!
* Lets us set advanced connection options with the `smbc_setOption*` functions (to be implemented).
* Ability to keep track of state, such as the last occurred error number (errno) for the connection.
* Automatic cleanup when PHP resource goes out of scope.
* Recommended method of access by the Samba authors.

So the typical usage will look like this (without errorchecking):

```php
$state = smbclient_state_new();
// Set extra options on the connection (not implemented yet)
smbclient_state_init($state, 'office', 'marcos', 'hunter2');
$dir = smbclient_opendir($state, 'smb://server/share');
while (($r = smbclient_readdir($state, $dir)) !== false) print_r($r);
smbclient_closedir($state, $dir);
smbclient_state_free($state);
```

Question for the audience: I've been playing around quite a bit with the naming of the new functions. I settled on 'state' as the name for the state resource, and on 'new/free' for the operations of acquiring and destroying it. So `smbclient_state_new` and `smbclient_state_free`. Is that sensible or should we go with `smbclient_context_init`/`smbclient_context_close`?