Access realms

it's role based. Users are assigned roles, roles are assigned permissions.

The realm is arbitrary. It can be pretty much anything you want. Basically it's a reference for a type of permissions.

If you look at the node_access_example.module, they have defined two realms: 'example', which has permission to view only, and 'example_author', which has permission to view, edit and delete.

It's kind of tricky to wrap your head around this concept, but basically what this is saying is that there are two types of users who will have permission to access the node in question. First, the word 'example' is kind of confusing, because in this case it doesn't example, it's just the title that they are using. So let's rename them for the sake of understanding. 'example' could be called 'user', and 'example_author' could be called 'author'. So these are two types of users who will access the content type - an author and a user.

Each time a node is saved, hook_node_access_records() is called, and the grants you are defining are attached to that node. I find it helpful to look at the db table - 'node_access'. You can see that the node id is saved along with the grants name, and a grant ID. Permissions are also saved, lets leave them for now. Basically, hook_node_access_records() tells Drupal that 'these types of users will have permission to do something on the node'.

Next, each time a node is accessed, hook_node_grants() is called. In this hook, some of the users data is compiled. It is then put in an array, and sent to the grants system. This array tells Drupal that 'this user is this type of user'. Drupal then compares the type of user that this is (hook_node_grants) with the type of user that is allowed to do something to the node (hook_node_access_records) and if there is a match, it allows them to use the permissions outlined in that row of the table.

So for example, with hook node_access_records, you can use this:

function mymodule_node_access_records($node)
{
  $grants = array();
  $grants[] = array
  (
    'realm' => 'node_author', // this name is arbitrary. It is basically a description of the type of user that will be allowed to access the node, in this case, the type of user is the author of the node that is being saved
    'gid' => $node->uid, // This is the uid of the author of the node being saved.
    'grant_view' => TRUE,  // The author of the node will have permission to view it
    'grant_update' => TRUE,  // the author of the node will have permission to edit it
    'grant_delete' => TRUE,  // The author of the node will have permission to delete it
    'priority' => 0,  // Until and unless you know what you are doing, leave this at zero
  );
  return $grants;
}

So now we have defined one type of user who will have access to the node. Remember, hook_node_access_records() is called for each node. That means that each and every single node will grant permissions to a user who matches the profile defined here. So lets look at how we check that:

function mymodule_node_grants($account, $op)
{
  // we have the user's details in the $account variable. So we can use them to create the user's profile
  $grants = array();
  $grants['author'][] = $account->uid; 
  return $grants;
}

Here we have built a profile of this user. We are giving the user's UID and telling the grants system to compare it to the 'author' realm. Again, this realm is arbitrary when setting it in hook_node_access_records(), but here we must use the realm that we defined there, or else we are comparing it to nothing. So lets look at this example:

1) User with a UID of 6 creates the node
2) hook node_access_records() saves the grant, saying that the author has a UID of 6
3) User with a UID of 10 tries to access the node
4) hook_node_grants() sends back the profile, which says that for the author realm, the UID is 10. Since the UID of the author was 6, the comparison fails, and the user isn't granted access.

1) User with a UID of 8 creates the node
2) hook_node_access_records() saves the grant, saying that the author has a UID of 8
3) User with a UID of 8 tries to access the node
4) hook_node_grants() sends back the profile, which says that for the author realm, the UID is 8. Since the UID of the author was 8, this comparison matches, and the user is granted the access permissions defined for that realm. In this case, that is viewing, editing and deleting permissions.

I hope this helps! The grants system is tricky to wrap your head around.